Skip to content

Repository files navigation

SecretPrinter

A Windows service that makes an AirPrint printer on one network reachable from another network, without joining those networks together.

Authorship. The source code, tests and documentation in this repository were written by Claude (Anthropic models: Claude Opus 4.5 for the original work, Claude Opus 5 and Claude Opus 5.5 for later changes), at the direction of Edwin West, and reviewed by a human before merge. Each file's header names the model that wrote it and, where a file has been changed since, the model that changed it; three files carry no header, and Section 13 names them. This is stated plainly because it is the point of the project, not a disclaimer buried in a footer. See Authorship and AI involvement.

This document is the specification. It is not an overview of the code; it is the definition the code must satisfy. Every normative statement carries an identifier such as REQ-ADV-001. Those identifiers appear in the source and in the tests, and a tool in this repository checks that every requirement has both, or, for a requirement that no code can meet, a named piece of evidence. See Section 11. (Corrected 2026-10-07 by Claude, Claude Opus 5.5: this said every requirement has both. Some rest on evidence, as Section 11 says.)

About the name

There is nothing secret about SecretPrinter.

It belongs to a family of projects — SecretArqc, SecretBeans, SecretCsv, SecretKey, SecretLetter and others — that share the prefix as a joke. The name means the opposite of what it says: every one of them is fully open, with its source, its reasoning, and its limitations published. The prefix is there to make that inversion obvious once you notice it.

If you arrived expecting something covert, the rest of this document is the correction.


Read this before installing

Six things about this software that you should know before it runs on your machine. They are here, at the top, because burying them would defeat the purpose of the project.

1. Your print jobs pass through the machine running this service. SecretPrinter is a proxy, not a router. Your phone sends the document to this service, and this service sends it to the printer. The document is held in memory on the proxy machine while that happens. A design that avoided this was evaluated and rejected as unworkable — see Section 2. If you are not comfortable with print jobs transiting that machine, do not use this software.

2. This deliberately departs from the mDNS standard. Multicast DNS (RFC 6762) is designed to be link-local: names ending in .local are meant to be meaningful only on one network segment. SecretPrinter makes a service on one segment visible on another. That is a considered departure from the specification, not an oversight, and it is why the service confines itself to printing.

3. It advertises what the proxy does, not what the printer does. The service does not copy the printer's advertisement wholesale. It publishes a narrower one describing what the proxy will actually deliver. Capabilities the proxy does not relay — scanning, faxing — are not advertised, even though the printer supports them. What it does publish says which printer is behind it: the printer's maker, model and product strings (usb_MFG, usb_MDL and product) are copied unchanged, with the entries that describe what will print. The whole list is beside REQ-ADV-009. And what the printer says inside the print conversation reaches the client unchanged, because the relay does not read what it carries (REQ-PXY-003). Measured on 2026-09-29: every reply carried the printer's Server header, which names its maker, and its replies carried links to port 80 at the proxy's own host name, where SecretPrinter serves nothing. An iPhone offers "Show Printer Web Page"; which link it uses, and where that leads, were not established (finding). (Added 2026-10-07 by Claude, Claude Opus 5.5.)

4. Your job is encrypted on one side and not the other. Between your phone and this service, the job travels as plain IPP over TCP, the same way it would to many printers on a home network. Between this service and the printer it is TLS, because this printer refuses to accept a job any other way. So the document is readable by anything that can see traffic on the client network, and the proxy is the point where it becomes encrypted. That is a deliberate choice for a home LAN rather than an oversight, and it is stated here so that anyone for whom it is not acceptable finds out before installing rather than after. The certificate the proxy will accept is pinned by fingerprint in configuration and checked on every connection; see Section 8.

5. The connection to the printer follows the Windows routing table. The service does not tie its connection to the printer to the printer-side network adapter. Windows chooses the way out from its routing table, as it would for any program. Normally that is the printer-side adapter, because it gives Windows the most specific route to the printer's address. On six occasions Windows has been measured choosing its default route instead, which sends the attempt to connect out on the client network, addressed to the printer and handed to the client network's router. The first time, the printer-side adapter had no link, as it would after a WLAN drop; it had been disconnected by hand for the measurement. The attempt was captured on the wire: five TCP SYN packets out the client-side Ethernet, to the router, and nothing answered. The second time, the printer-side adapter was up, with its address and its route to the printer's network, but the printer had stopped answering on that network. Measured again after the printer had come back, Windows chose the printer-side adapter. Why Windows chose the default route while the adapter was up was not established, and that time no packets were captured. The third time, two attempts in a row took the default route and failed, and a later one took the printer-side adapter and connected; the state of that adapter during the first two was not read, no packets were captured, and by the operator's account nothing was reconnected by hand in between. The fourth time, Windows reported the printer-side adapter up and connected, holding its address and its route to the printer's network, and nothing on that network answered it, while the printer was answering another machine on the same network. After the adapter was reconnected by hand, Windows chose it. The fifth time, on 2026-10-14, one attempt took the default route while the printer was not answering on its own network; a few minutes later Windows reported the printer-side adapter holding its address, and routed to the printer through it. Its state at the moment of the attempt was not read. The sixth time, later on 2026-10-14, after Windows had restarted, the printer-side adapter had no link, as the first time, and one attempt took the default route and was not answered. A script of Edwin West's, which is not part of SecretPrinter, has also tested the printer's port on that machine every ten minutes since 2026-10-09, with Test-NetConnection. To 2026-10-19 it ran 1,444 tests. All 1,224 that succeeded went through the printer-side adapter. Of the 220 that failed, 213 took the default route: 174 while the service held the printer unreachable, 38 while the service, started again after a Windows restart, was waiting for a printer that did not answer, and one while the service still held the printer reachable; by the next test, ten minutes later, it held it unreachable. At every one of those 213 the gateway of the printer's network had answered the script's pings, and at all but five the script had found the printer-side adapter up; at those five it had just connected it. The other seven failures went through the printer-side adapter. The first two occasions and the fourth were measured with Windows' own tools, Test-NetConnection and Find-NetRoute, the third and the sixth with Test-NetConnection alone, and the fifth with Test-NetConnection and, minutes later, Find-NetRoute; the script uses Test-NetConnection. None of them was the service's connection. No print job goes that way. The service sends job data only after a TLS handshake with the pinned printer succeeds, and a connection that is never answered never gets that far. What does leave is the attempt itself: the printer's address and port, from the proxy's client-side address. The same fact has a further consequence, which follows from how routing works but has not been measured: if another adapter on the machine is connected to the printer's network, Windows may route the connection through that adapter rather than the one the configuration names. What the router does with such packets was not observed either. See the findings of 2026-09-22, 2026-09-27, 2026-10-03, 2026-10-06, 2026-10-14, later that day, 2026-10-18 and 2026-10-19. (Updated 2026-10-03 by Claude, Claude Opus 5.5: until then this point said two occasions and described two. Updated 2026-10-07 by Claude, Claude Opus 5.5: it said three; the fourth was measured on 2026-10-06 and recorded in that day's finding, and was not carried here. Updated 2026-10-14 by Claude, Claude Opus 5.5: it said four occasions; the fifth is new. Updated again later that day by Claude, Claude Opus 5.5: it said five occasions and "the third with Test-NetConnection alone", and its links ended at the first finding of 2026-10-14; the sixth is new. Updated 2026-10-18 by Claude, Claude Opus 5.5: it said six occasions and "the third and the sixth with Test-NetConnection alone"; the seventh and eighth are new, read from that script's log from 2026-10-15 on. Its log before then was not read for this. Updated 2026-10-19 by Claude, Claude Opus 5.5: it said eight occasions, the seventh and eighth being that script's tests of 2026-10-16 and 2026-10-17, and "the third, the sixth, the seventh and the eighth with Test-NetConnection alone"; the paragraph on the script now gives its whole log to 2026-10-19 in their place.)

6. It has been measured in one household. Every measurement on a network that this document reports was made in one household: on one person's machines and networks, with one printer model, an Epson ET-3760, and on three Windows machines. The client was an iPhone on almost every occasion; a second device printed through the proxy once (finding). No other printer and no other household's network has been tried. Where a statement rests on a single run, the finding it links to says so. Which versions of Windows it has run on, and for how long, is under open question 10. (Added 2026-10-07 by Claude, Claude Opus 5.5. Each fact here was already in this document or its findings; none of them was at the top.)

Known problems

What is known to go wrong, or to fall short, as of 2026-10-08. Each is on record in the finding or the requirement named beside it. (Section added 2026-10-07 by Claude, Claude Opus 5.5, when this document was read against the code and the findings from its first line to its last; the finding lists what that reading changed. Date changed 2026-10-08, when every entry was read again after the published pre-release was installed from nothing, and one entry was rewritten (finding). On 2026-10-10 the entry on RFC 6762 was rewritten when the first of its four items was built, and the entry on the printer-side network when REQ-RES-010 was built; the other entries were not read again that day. On 2026-10-11, after REQ-RES-010 ran overnight on FIOS-STB-01, the entry on the printer-side network was changed and the entry after it added, and later that day, when release 0.2.0 was installed, the entry on RFC 6762 was given a sentence; the other entries were not read again that day. On 2026-10-12 the entry on RFC 6762 was rewritten when the second of its four items was built (REQ-ADV-027), and given a sentence later that day when it was run on a network; the other entries were not read again that day. On 2026-10-13 the entry on releases 0.1.0 and 0.2.0 answering a legacy query at any address was added (REQ-SEC-017), and later that day the entry on RFC 6762 was rewritten when the third of its four items was built (REQ-ADV-028) and the entry on the TTL of a unicast answer given a sentence, and later again given a sentence when it was run on a network; later still, the entry on RFC 6762 was rewritten when the last of its four items was built (REQ-ADV-029); the other entries were not read again that day. On 2026-10-14 the entry on RFC 6762 was given a sentence when the last of its four items was run on a network, and the entry on questions sent by unicast to port 5353 was added; later that day the entry on releases 0.1.0 and 0.2.0 not stopping cleanly when Windows shuts down was added (REQ-LIF-009), and later still changed when the correction was run at a real restart; the other entries were not read again that day. On 2026-10-15, in the commit that sets the version to 0.3.0, those two entries on releases 0.1.0 and 0.2.0 were changed to name 0.3.0 as the first version to carry each correction, and later that day, once 0.3.0 had been published, they were made exact; the other entries were not read again that day. On 2026-10-20 the entry on the printer-side network was given sentences on a Windows policy, which this note did not record until 2026-10-22; on 2026-10-22 it was given two on the printer's own announcements, which were changed later that day when REQ-RES-011 was built, and again that evening when it was run on a network; the other entries were not read again on either day. On 2026-10-25, in the commit that sets the version to 0.5.0, that entry was changed to name 0.5.0 as the first version to carry REQ-RES-011, and later that day, once 0.5.0 had been published, it was made exact; the other entries were not checked again that day. On 2026-10-26 the entry on lookups that take a response sent by unicast or from another port was added (REQ-RES-012), and later that day the entry on answers believed for as long as their TTL says (REQ-RES-013); later still, after a build carrying both ran on FIOS-STB-01, those two entries were changed and the entry on a print attempt that sends no job given a sentence; the other entries were not read again that day. On 2026-10-27 the entry on a conflict shown by a response sent by unicast or from another port was added (REQ-ADV-030), and changed that evening, after a build carrying it ran on FIOS-STB-01; the other entries were not read again that day. On 2026-10-28 the entry on the probe keeping any DNS response that reaches it was added (REQ-SEC-018); the other entries were not read again that day. On 2026-10-30, in the commit that sets the version to 0.6.0, the four entries on releases up to 0.5.0 for REQ-RES-012, REQ-RES-013, REQ-ADV-030 and REQ-SEC-018 were changed to name 0.6.0 as the first version to carry each correction, and later that day, once 0.6.0 had been published, they were made exact; the other entries were not checked again that day.)

  • A print attempt can reach the printer and send no job. On 2026-10-01 and 2026-10-02, in three attempts, an iPhone connected through the proxy, had every request answered, and sent no job. In two of them it showed a message that it could not reach the printer. A later attempt printed on both days. The cause is not established (finding). Seen again once on 2026-10-26, on FIOS-STB-01 in a build of de1d171: the iPhone said it could not contact the printer while the service relayed every connection to the printer and logged no failure, and the next attempt printed (finding). (Sentence added 2026-10-26 by Claude, Claude Opus 5.5.)
  • An iPhone that has printed to the printer directly may show the printer's own name. On such an iPhone the list has held two rows, the proxy's and one with the printer's own name, and picking the proxy's row has turned the selection into the printer's name. Each time the log was read, the page had gone through the proxy. A second device, which had not printed to the printer, kept the proxy's name, by Edwin West's account. Why iOS does this is not established (2026-09-21, 2026-09-29, 2026-10-06, 2026-10-08).
  • When the printer-side network drops, the printer disappears from the client network, and it can be slow to come back. The service stops offering a printer it cannot reach (REQ-LIF-006) and asks for it less and less often, down to once an hour (REQ-RES-008). Since 2026-10-10, when Windows reports the printer-side adapter usable again, the service asks at once and starts that sequence over (REQ-RES-010). That helps when the printer answers soon after its network is back. When the printer itself stays away for longer, it can again take up to an hour to be found, and, worked out from the code, one loss in 0.1.0's record would have ended 26 to 35 minutes later with the start over than without it (finding). On 2026-10-21 the printer was seen, once, to announce itself eight times in about two minutes after it was switched on, as RFC 6762 §8.3 describes. Releases up to 0.4.0 keep what arrives from the printer only while one of their own questions is waiting for an answer, so they use those announcements only if a question happens to be waiting (finding). Since 2026-10-22 the service takes them as an answer while it holds the printer unreachable (REQ-RES-011) (finding). Run once on FIOS-STB-01 that evening, in a build from source, it offered the printer again no more than about 40 seconds after it was switched on, when its next question was about 3 minutes away. About 5 minutes later the service's questions went unanswered and it withdrew the printer again, until one was answered about 5 minutes after that; why is not shown. Release 0.5.0, published on 2026-10-25, is the first to carry it (finding). Overnight on FIOS-STB-01 on 2026-10-10 and 2026-10-11 the start over acted three times, each within 3 seconds of the Wi-Fi being reconnected, and the printer was offered again within 6 seconds of the reconnect. Each time the Wi-Fi had stayed down, for 3 min 37 s to 7 min 44 s, until a script of Edwin West's reconnected it (finding). Microsoft documents a Windows policy, on by default, that in one of its settings blocks a new automatic internet connection while an Ethernet one is up, and FIOS-STB-01 behaved as that setting describes. With it set to 0 on FIOS-STB-01 on 2026-10-19, Windows reconnected the Wi-Fi by itself at the next two drops, about two seconds after each (finding). Changing that policy is the owner's decision, and a Windows 10 security guideline counts the value 0 as a finding; docs/operating.md says what it does. Restarting the service brings the printer back at once. The service does not reconnect a dropped Wi-Fi link, because that would change the host's network configuration (REQ-SEC-007). See docs/operating.md. (Rewritten 2026-10-10 by Claude, Claude Opus 5.5. It said that after a long outage the printer could stay away for up to an hour after the link returned. Changed 2026-10-11 by Claude, Claude Opus 5.5: in place of the sentence on the overnight run it said "None of this has been run on a network yet." Updated 2026-10-20 by Claude, Claude Opus 5.5: the sentences on the Windows policy added. Updated 2026-10-22 by Claude, Claude Opus 5.5: the sentences on the printer's announcements added, and changed later that day when REQ-RES-011 was built; they said the service "does not use those announcements unless a question happens to be waiting". Changed again that evening, when REQ-RES-011 was run on a network: the sentence on it ended "no release carries that yet, and it has not been run on a network". Changed 2026-10-25 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.5.0: the sentence on the run ended "No release carries this yet". Made exact later that day, once 0.5.0 had been published: it ended "0.5.0, the fifth version meant as a release, is the first to carry it".)
  • For a short time after the printer stops answering, it is still offered, and a print in that time fails. The service holds the printer reachable until its records expire with no answer to the service's own questions; a question a print job asks that goes unanswered does not count (REQ-RES-008). On FIOS-STB-01 on 2026-10-10, 12 connections failed in the 80 seconds before the service withdrew the printer, and on 2026-10-11 the printer was still offered for 98 seconds after the printer-side Wi-Fi was disconnected (finding). (Entry added 2026-10-11 by Claude, Claude Opus 5.5.)
  • Any device on the client network can make the printer disappear until the service is restarted, by answering for a name the service advertises (REQ-ADV-024). mDNS has no authentication.
  • Releases 0.1.0 and 0.2.0 answer a legacy mDNS query by unicast to whatever address it gives. A device on the client network that forged the source address of such a query could have the service send its answer, the printer's advertisement, out of the printer-side adapter, or through a router to an address on neither network, and the answer is many times the size of the question. Not seen on a network. Corrected on main on 2026-10-13 (REQ-SEC-017); release 0.3.0, published on 2026-10-15, is the first to carry the correction (finding). (Entry added 2026-10-13 by Claude, Claude Opus 5.5. Changed 2026-10-15, in the commit that sets the version to 0.3.0: it said "no release carries the correction yet". Made exact later that day, once 0.3.0 had been published: it said "0.3.0, the third version meant as a release, is the first to carry the correction".)
  • Releases 0.1.0 and 0.2.0 do not stop cleanly when Windows shuts down or restarts. The service logs that it is stopping, and then its process ends with an exception nothing catches: it sends no goodbye records, closes nothing in order and writes no summary. A client may go on listing the printer after the machine has gone down, until the records expire: two minutes for the address records, 75 minutes for the browse and TXT records. Seen on FIOS-STB-01 on 2026-10-14, when nothing was offered. Corrected on main on 2026-10-14 (REQ-LIF-009) (finding), and run at a real restart on FIOS-STB-01 the same day, with the printer offered: the service logged sending its goodbye, wrote its summary and stopped, and Windows recorded no application error (finding). Release 0.3.0, published on 2026-10-15, is the first to carry it. (Entry added 2026-10-14 by Claude, Claude Opus 5.5. Changed later that day, after the run at a real restart: it ended "no release carries the correction yet, and it has not been run at a real restart", followed by the first finding's link. Changed again 2026-10-15, in the commit that sets the version to 0.3.0: it ended "No release carries the correction yet." Made exact later that day, once 0.3.0 had been published: it ended "0.3.0, the third version meant as a release, is the first to carry it.")
  • A service that fails after it has started stays stopped until it is started again. A part of the running service that fails, such as a relay that cannot open its listeners (REQ-ADV-021), stops the whole service: it says goodbye, logs why, and as a Windows service ends its process. Until 2026-10-07 the rest of the service ran on and the process stayed, shown as running (finding). Run under Windows on 2026-10-08, with the listener made to fail on purpose: the service ended within about three seconds of starting, Windows then showed it STOPPED with error 1067, "The process terminated unexpectedly", and recorded event 7034, "terminated unexpectedly". The exit code 4 is in the log only. The install steps set no recovery action, and whether one set with sc.exe failure would run is not measured (finding). (Entry rewritten 2026-10-08 by Claude, Claude Opus 5.5, after that run. It was headed "What Windows shows when the service fails after it has started has never been measured", and said the end of the process "has not been run". It had been rewritten once before, on 2026-10-07, the day it was written; it had then read "Windows is not told" and "Not yet corrected".)
  • A client may go on listing the printer after the service has stopped. The goodbye is sent over IPv4 only (REQ-LIF-003). An iPhone has been seen keeping the entry after one, and on another day dropping it within about three seconds (docs/operating.md).
  • A change of address on the client side needs a restart. The client interface's addresses are read once, at startup (REQ-ADV-021).
  • A connection that is open when the service stops, or when it withdraws the printer, is cut, and the log has no line for its end (REQ-PXY-009).
  • Three things RFC 6762 asks about the timing of answers are not done (REQ-ADV-029). A query marked truncated is not given the 400 to 500 milliseconds §6 asks for, so that the known answers in the packets after it can arrive. Answers are not held for up to 500 milliseconds so that several go in one message, which §6 says a responder on Ethernet should be able to do. And while one answer waits its random 20 to 120 milliseconds, the service reads no other query, so when several queries that each take the wait arrive together, a later answer can go more than 120 milliseconds after it was asked. All three are recommendations of the standard. The four things recorded as not done on 2026-10-07 (finding) are done. The last, waiting a random 20 to 120 milliseconds before an answer that other devices may be sending too (§6 and §6.3), also a recommendation, is done since later on 2026-10-13 (REQ-ADV-029); that has been measured against the code by tests (finding) and run on a network once, on FIOS-STB-01, where each of the 17 queries answered, of 831 seen, was answered after the wait, three of them timed at 62 to 115 milliseconds after their questions, and an iPhone printed a page (finding). (Updated 2026-10-14 by Claude, Claude Opus 5.5: it said "and not yet run on a network".) Another, answering by multicast when a question from port 5353 asks for a unicast answer (§5.4), also a recommendation, is done since 2026-10-13 (REQ-ADV-028); that has been measured against the code by tests (finding) and run on a network once, on the test machine, where 29 of the 31 queries answered were answered by unicast because they asked for it, and an iPhone printed a page (finding). (Updated later on 2026-10-13 by Claude, Claude Opus 5.5: it said "has not yet been run on a network".) A third, sending the same record by multicast more than once in a second (§6), a requirement of the standard, is done since 2026-10-12 (REQ-ADV-027). It had been seen on a network on 2026-10-02. That it is done has been measured against the code by tests (finding) and run on a network once, on the test machine, where 4 of the 116 queries seen were not answered because their answer would have repeated records multicast less than a second before, and an iPhone printed a page (finding). (Updated later on 2026-10-12 by Claude, Claude Opus 5.5: it said "has not yet been run on a network".) A fourth, answering a question that already carries the answer (§7.1), is done since 2026-10-10 (REQ-ADV-026); that has been measured against the code by tests (finding) and run on a network once, on the test machine, where 26 of an iPhone's queries carried every answer and went unanswered and a page printed (finding). (Updated later on 2026-10-10 by Claude, Claude Opus 5.5: it said "has not yet been run on a network".) It then ran on FIOS-STB-01 for nearly 23 hours, from 2026-10-10 to 2026-10-11, and left 64 of 9,365 questions unanswered because they carried every answer (finding). (Sentence added 2026-10-11 by Claude, Claude Opus 5.5.) The places where the service departs from the standard on purpose are in the rows that make the decision: REQ-ADV-021, REQ-ADV-023 and REQ-ADV-024. (Rewritten 2026-10-10 by Claude, Claude Opus 5.5. It was headed "Four things RFC 6762 asks of a responder are not done" and listed §7.1 first.) (Rewritten 2026-10-12 by Claude, Claude Opus 5.5. It was headed "Three things RFC 6762 asks of a responder are not done" and listed first that the service would send the same record by multicast more than once in a second.) (Rewritten 2026-10-13 by Claude, Claude Opus 5.5. It was headed "Two things RFC 6762 asks of a responder are not done" and listed second that the service answers by multicast when a question from port 5353 asks for a unicast answer.) (Rewritten later still on 2026-10-13 by Claude, Claude Opus 5.5. It was headed "One thing RFC 6762 asks of a responder is not done" and began by saying that the service does not wait the random 20 to 120 milliseconds before answering for a name it shares with other devices. The three things it now begins with were found while that was built; the first was already stated in REQ-ADV-026.)
  • A question sent by unicast straight to the service's port 5353 has not been seen answered (REQ-ADV-028). RFC 6762 §5.5 says that a responder receiving one "SHOULD respond as it would for "QU" questions". An iPhone has sent such questions on 2026-10-01, 2026-10-02 and 2026-10-14, and none was answered. On 2026-10-01 and 2026-10-14 it asked the same by multicast within about a third of a second and was answered, and on each of the three days a page printed. Why they went unanswered is not established; one possibility, not tested, is that Windows' own DNS Client, which also uses port 5353, receives them (finding). (Added 2026-10-14 by Claude, Claude Opus 5.5. It had been recorded in the findings of 2026-10-01 and 2026-10-02 and not stated here.)
  • Whether an IPv4 answer sent by unicast leaves with TTL 255 is not established (REQ-ADV-013). Since 2026-10-13 that includes an answer sent by unicast because a question asked for one (REQ-ADV-028).
  • The permitted client network is worked out from the client interface's address, not read from its subnet mask (REQ-SEC-012).
  • Releases up to 0.5.0 take a response sent by unicast, or from a port other than 5353, as the answer to a lookup on the printer-side network. RFC 6762 §6 says a querier must silently ignore a unicast response that answers no question asking for one, which none of the service's questions does, and any response whose source port is not 5353. The printer's answers to the service's questions were heard on 2026-10-21 by a listener on another machine on that network, which a unicast answer to the service's machine would not have reached; whether this ever made a difference is not known. Corrected on main on 2026-10-26 (REQ-RES-012); measured against the code by tests (finding), and run once on a network later that day, on FIOS-STB-01, where the printer's answers were taken and a page printed; release 0.6.0, published on 2026-10-30, is the first to carry the correction (finding). (Entry added 2026-10-26 by Claude, Claude Opus 5.5. Changed later that day: it said "not yet run on a network". Changed 2026-10-30 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.6.0: it said "no release carries the correction". Made exact later that day, once 0.6.0 had been published: it said "0.6.0, the sixth version meant as a release, is the first to carry the correction".)
  • Releases up to 0.5.0 believe an answer from the printer-side network for as long as its TTL says, however long. A device on that network that answered one of the service's questions with a very long TTL would have its address reused by print jobs, and the printer held reachable, for most of that time before the service asked again. A forged address still meets the pinned certificate (REQ-SEC-013), so the jobs would fail rather than reach the device. Read from the code; not seen. Corrected on main on 2026-10-26: no answer is believed for more than 120 seconds, the TTL RFC 6762 §10 recommends for the records an answer is made of (REQ-RES-013); measured against the code by tests (finding), and run once on a network later that day, on FIOS-STB-01, where the printer's answers had a lifetime of 120 seconds and nothing was capped; release 0.6.0, published on 2026-10-30, is the first to carry the correction (finding). (Entry added later on 2026-10-26 by Claude, Claude Opus 5.5. Changed later still that day: it said "not yet run on a network". Changed 2026-10-30 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.6.0: it said "no release carries the correction". Made exact later that day, once 0.6.0 had been published: it said "0.6.0, the sixth version meant as a release, is the first to carry the correction".)
  • Releases up to 0.5.0 take a response sent by unicast, or from a port other than 5353, as showing a conflict on the client network. RFC 6762 §6 says an mDNS implementation must silently ignore any response whose source port is not 5353, and a querier any unicast response that answers no question of its own that asked for one; the service's only questions there are its probes, which ask for multicast answers. A device on the client network can make the service withdraw by answering for its names whatever it does (REQ-ADV-024); what this changes is that a response that should have been ignored was read. Read from the code; not seen. Corrected on main on 2026-10-27 (REQ-ADV-030); measured against the code by tests (finding), and run once on a network that evening, on FIOS-STB-01, where its probe came back clear and a page printed; release 0.6.0, published on 2026-10-30, is the first to carry the correction (finding). (Entry added 2026-10-27 by Claude, Claude Opus 5.5. Changed that evening: it said "not yet run on a network". Changed 2026-10-30 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.6.0: it said "no release carries the correction". Made exact later that day, once 0.6.0 had been published: it said "0.6.0, the sixth version meant as a release, is the first to carry the correction".)
  • The probe in releases up to 0.5.0 keeps any DNS response that reaches it. The probe, SecretPrinter.Probe, asks from a port the operating system chooses, so a responder answers it by unicast (RFC 6762 §6.7). It kept every DNS response that reached that port, from any port and with any identifier, printed it in its report, and asked its next round of questions about the names in it. RFC 6762 §6 says every mDNS response comes from port 5353 and that a querier "MUST only accept unicast responses if they answer a recently sent query", and §6.7 that such an answer "MUST repeat the query ID". Read from the code; not seen. Corrected on main on 2026-10-28 (REQ-SEC-018); measured against the code by tests, and run once on the printer-side network from the development machine, where the printer's replies were kept as before; release 0.6.0, published on 2026-10-30, is the first to carry the correction (finding). The correction does not make a reply trustworthy: any device on that network can see the probe's question and answer it as the printer would. (Entry added 2026-10-28 by Claude, Claude Opus 5.5. Changed 2026-10-30 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.6.0: it said "no release carries the correction". Made exact later that day, once 0.6.0 had been published: it said "0.6.0, the sixth version meant as a release, is the first to carry the correction". On 2026-10-30 the probe of release 0.6.0 was run on FIOS-STB-01, from the release's own folder; the second time it was run it kept the printer's replies and ignored nothing, and the first time the printer did not answer it (finding).)

Table of contents

  1. Problem
  2. Why a proxy and not a reflector
  3. Architecture
  4. Requirements: advertisement (ADV)
  5. Requirements: resolution (RES)
  6. Requirements: relay (PXY)
  7. Requirements: configuration (CFG)
  8. Requirements: security and trust (SEC)
  9. Requirements: lifecycle and observability (LIF, OBS)
  10. Requirements: build and distribution (DIST)
  11. How to validate this README against the code
  12. Repository layout
  13. Authorship and AI involvement
  14. Open questions
  15. License

1. Problem

A household has an AirPrint printer on one wireless network. Phones and laptops on a second, unrelated network cannot print to it.

The two networks have no route between them. They are separate consumer networks with separate gateways, and the second gateway offers no way to add a static route. One machine is connected to both.

Two things must be true for AirPrint to work, and both fail here:

Requirement Status across separate networks
The client can discover the printer Fails: mDNS is link-local and does not cross subnets
The client can reach the printer's IP Fails: no route exists between the networks

Fixing only the first produces a printer that appears in the list and then fails on every job: the client is given the printer's own address, which it has no route to (Section 2).

2. Why a proxy and not a reflector

The obvious design is an mDNS reflector: copy multicast DNS packets from one network to the other, unmodified. It is simple, and it is what most existing tools do.

It does not work here, for a specific reason. The printer's mDNS response contains an A record with its own address on its own network. A reflector copies that response unmodified — that is what makes it a reflector. The client then believes the printer lives at an address it has no route to, and the connection fails at TCP.

A reflector is the correct design when IP routing already works between the segments and only discovery is missing. That was not the case here, and could not be made the case.

SecretPrinter therefore acts as a proxy. It advertises itself on the client network, at an address clients can reach, and relays the print job to the real printer over its other interface.

Reflector Proxy (chosen)
Requires routing between networks Yes No
Sees print job contents No Yes
Survives printer address changes Yes Yes, via runtime resolution
Exposes non-printing services Yes, all of them No

The proxy's cost is real and is disclosed at the top of this document: job data transits the proxy machine. The reflector's cost is that it does not work in this situation, and additionally that it bridges every mDNS service on both networks, not only printers.

3. Architecture

   CLIENT NETWORK                PROXY HOST                PRINTER NETWORK
                          (dual-homed Windows machine)

  ┌──────────┐                ┌──────────────┐               ┌──────────┐
  │  Phone   │                │ SecretPrinter│               │ Printer  │
  │          │  1. discover   │              │               │          │
  │          │ ──────────────>│  Advertiser  │               │          │
  │          │ <──────────────│  (mDNS)      │               │          │
  │          │  2. proxy's    │              │               │          │
  │          │     own addr   │              │  3. resolve   │          │
  │          │                │  Resolver    │ ─────────────>│          │
  │          │  4. IPP job    │  (mDNS)      │ <─────────────│          │
  │          │ ──────────────>│              │               │          │
  │          │                │  Relay       │  5. IPP job   │          │
  │          │                │  (TCP)       │ ═══TLS═══════>│          │
  └──────────┘                └──────────────┘               └──────────┘
  1. The phone browses for AirPrint printers on the client network.
  2. SecretPrinter answers, advertising itself at its own client-network address.
  3. On receiving a connection, SecretPrinter resolves the real printer's current address by mDNS on the printer network.
  4. The phone sends the IPP job to SecretPrinter.
  5. SecretPrinter opens a TLS connection to the printer and relays the job.

Step 4 is plaintext and step 5 is encrypted. That is not a preference; the ET-3760 answers Get-Printer-Attributes over plain IPP but refuses Validate-Job with 426 Upgrade Required, so a job cannot be submitted without TLS. The printer advertises _ipps._tcp on the same port 631 and accepts TLS from the first byte, which is why the relay needs no HTTP upgrade handshake and still parses nothing it carries. Measured on 2026-09-15; see findings.

Step 5 is not bound to the printer-side interface. The relay's outbound socket is created without a local address, so Windows chooses its path from the routing table. Normally that is the printer network. Windows has been measured choosing the default route on the client network on six occasions: twice with the printer-side link down; once with the link up while the printer was not answering on its network; once with the adapter reported up while nothing on its network answered it; and twice with the adapter's state at that moment not read. A script that tests the printer's port every ten minutes found the same at 213 of its 220 failed tests from 2026-10-09 to 2026-10-19, 212 of them while the service was not offering the printer, and at none of its 1,224 tests that succeeded. Why Windows chose that with the adapter up is not established. All were measured with Windows' own tools, not with the relay's socket. This is disclosed as the fifth item under Read this before installing. (Updated 2026-10-07 by Claude, Claude Opus 5.5: this paragraph described two occasions. The fifth item had described three since 2026-10-03, and a fourth was measured on 2026-10-06.) (Updated 2026-10-18 by Claude, Claude Opus 5.5: it said four occasions: "with the printer-side link down; with the link up while the printer was not answering on its network; once with the adapter's state not read; and with the adapter reported up while nothing on its network answered it", and "All four". The fifth and sixth, measured on 2026-10-14, had been added to the fifth item that day but not here; the seventh and eighth are new. See the finding.) (Updated 2026-10-19 by Claude, Claude Opus 5.5: it said eight occasions, "three times with the link up while the printer was not answering on its network" and "All eight"; the seventh and eighth were that script's, and its whole log to 2026-10-19 now stands in their place. See the finding.)

The address and port for step 5 come from the printer's _ipps._tcp service, and the capabilities advertised in step 2 come from the TXT record of its _ipp._tcp service (REQ-RES-007). On this printer both services name port 631. That is observed, not relied on.

Steps 3 and 5 use IPv4 only. The service asks the printer over IPv4, takes the printer's A record, and connects to that address; its printer-side socket does not join the IPv6 group. Steps 1, 2 and 4 use IPv4 and IPv6 (REQ-ADV-018, REQ-ADV-021). (Paragraph added 2026-10-07 by Claude, Claude Opus 5.5; it describes the code as it has been since the IPv6 work, and this section did not say it.)

Address resolution happens at connection time, because printers receive their addresses by DHCP and those addresses change. During development the target printer was seen at two addresses in one session (finding). (Corrected 2026-10-07 by Claude, Claude Opus 5.5: this said the printer "moved twice". The record holds two addresses, which is one move.) Startup also resolves both services, before anything is advertised, and takes the capabilities from that answer. Until both have answered, and before that until the printer-side adapter is usable at all, the service offers nothing to the client network and waits (REQ-LIF-008). A configuration naming a service the printer does not advertise therefore waits too, and says so in the log; the service cannot tell that from a printer that is switched off. Each connection still resolves for itself, reusing an earlier answer only as REQ-RES-004 allows.

4. Requirements: advertisement (ADV)

What the service publishes on the client network.

ID Level Requirement
REQ-ADV-001 MUST The service advertises an IPP printer service (_ipp._tcp.local) on each configured client interface.
REQ-ADV-002 MUST The service advertises the AirPrint subtype _universal._sub._ipp._tcp.local. Measured: iOS queries this subtype exclusively and never the base service type, so a responder omitting it is never discovered.
REQ-ADV-003 MUST The SRV record published for the proxy names a hostname owned by the proxy, and the A record for that hostname contains the proxy's own address on the interface the query arrived on.
REQ-ADV-004 MUST NOT The service publishes the real printer's IP address, hostname, or A record on the client network.
REQ-ADV-005 MUST NOT The service publishes the real printer's UUID TXT value. It publishes its own UUID, distinct per advertised service, which is explicit configuration (advertise.uuid): the operator generates it, the configuration file is what keeps it, the service refuses to start without one (REQ-CFG-001), and it will not build an advertisement with one equal to the printer's. (Corrected 2026-10-07 by Claude, Claude Opus 5.5: this row said the service "generates and persists its own UUID". It has never generated one: REQ-CFG-001 forbids a default, and docs/operating.md has the operator generate it. The reading of the README earlier the same day did not catch that. Until the same day the example configuration the program prints carried a fixed UUID that loaded, so every installation whose operator left it in advertised the same one. The example now prints the entry empty. See the finding.)
REQ-ADV-006 MUST NOT The service publishes any TXT key asserting a capability the proxy does not relay. As of this version that includes Scan and Fax.
REQ-ADV-007 MUST NOT The service publishes a certification claim it does not itself hold, including mopria-certified.
REQ-ADV-008 MUST Any adminurl published either points at a resource reachable from the client network, or is omitted. The printer's own adminurl is never copied verbatim.
REQ-ADV-009 MUST Format-capability TXT keys obtained from the printer (pdl, URF, Color, Duplex, PaperMax, kind) are published unchanged, because they describe what will actually print. (Note, 2026-10-07, by Claude, Claude Opus 5.5: the six keys named are not all that is copied. The code copies fourteen keys when the printer publishes them, from a list in src/SecretPrinter.Advertising/AdvertisementBuilder.cs: txtvers, rp, qtotal, priority, pdl, URF, Color, Duplex, PaperMax, kind, Sides, usb_MFG, usb_MDL and product. The last three name the printer's maker and model. It adds three entries of its own: ty, holding the advertised instance name; note, saying that this is a proxy and when the capabilities were read; and UUID, its own (REQ-ADV-005). Every other entry the printer publishes is dropped, and the startup log lists each one with the reason (REQ-OBS-003).)
REQ-ADV-010 MUST The advertised TXT record set is derived from a live query to the printer, never from values hardcoded in source.
REQ-ADV-011 MUST NOT The service advertises on any interface not listed in configuration as a client interface. (Note, 2026-10-13, by Claude, Claude Opus 5.5: until this date an answer sent by unicast could leave by the printer-side adapter. The service answered a legacy query (REQ-ADV-017) by unicast to whatever address the query gave, and Windows chooses the adapter a unicast datagram leaves by from its routing table, so a query on the client network with a forged source address on the printer network would have had its answer sent there. Measured against the code with a fake transport; not seen on a network. Corrected by REQ-SEC-017; see the finding.)
REQ-ADV-012 MUST The service responds only to queries for names it advertises, and ignores all other mDNS queries. Those names are its two service-type names (REQ-ADV-001, REQ-ADV-002); the DNS-SD service enumeration name _services._dns-sd._udp.local (RFC 6763 §9), under which it lists _ipp._tcp.local; its service instance name; and its host name. (Corrected 2026-10-07 by Claude, Claude Opus 5.5: this said "only to queries for service types it advertises". The code also answers for the instance name and the host name, as REQ-ADV-003 and REQ-ADV-022 need, and for the enumeration name, which this document did not mention anywhere.)
REQ-ADV-013 MUST Outgoing mDNS packets carry IP TTL 255, per RFC 6762 §11. (Note, 2026-10-07, by Claude, Claude Opus 5.5: not established for one kind of packet. The code sets the multicast TTL. An IPv4 answer sent by unicast to a legacy querier (REQ-ADV-017) takes a different setting, which the code does not set, so by the reasoning in the finding of 2026-09-06 it leaves with the Windows default and not 255. No capture has been taken to settle it. The IPv6 path sets both settings (REQ-ADV-019).) (Note, 2026-10-13, by Claude, Claude Opus 5.5: an IPv4 answer sent by unicast because a question asked for one (REQ-ADV-028) takes the same setting, so the same is not established for it.)
REQ-ADV-014 MUST The service binds UDP 5353 with SO_REUSEADDR and does not require exclusive use of the port, so it coexists with the Windows DNS Client service.
REQ-ADV-015 MUST The arrival interface of each received query is determined from IP_PKTINFO, not inferred from the socket's bound address.
REQ-ADV-016 SHOULD The advertised instance name makes the proxy's role evident to a person reading the printer list, rather than impersonating the printer.
REQ-ADV-017 MUST The service identifies legacy unicast queriers by a source port other than 5353 (RFC 6762 §6.7), answers them by unicast rather than multicast, echoes the query identifier, and caps response TTLs. (Note, 2026-10-13, by Claude, Claude Opus 5.5: only a querier whose address is on the network its query arrived from is answered (REQ-SEC-017). Until that day every one was, at whatever address its query gave.)
REQ-ADV-018 MUST The service receives and answers mDNS queries over IPv6 on ff02::fb port 5353, on each configured client interface, in addition to IPv4 on 224.0.0.251. It answers with the same records it would send over IPv4, delivered over the address family the query arrived on: a query received over IPv6 is answered over IPv6, a query received over IPv4 over IPv4, and neither is answered over both. Measured: an iPhone on the client network sent the same mDNS queries over IPv4 and IPv6, and only the IPv6 copies reached the service's machine, so a responder holding an IPv4 socket alone did not receive the question. Where the IPv4 copies were lost is not established; see findings.
REQ-ADV-019 MUST Outgoing IPv6 mDNS packets carry hop limit 255, per RFC 6762 §11, as REQ-ADV-013 requires of the IPv4 TTL.
REQ-ADV-020 MUST The arrival interface of a query received over IPv6 is determined from IPV6_PKTINFO, not inferred from the socket's bound address, as REQ-ADV-015 requires for IPv4.
REQ-ADV-021 MUST The service publishes an AAAA record for its own hostname for each IPv6 link-local address (fe80::/10) that the client interface holds in the preferred state, and no other IPv6 address: not the interface's global or unique local addresses, whether public or temporary, and nothing from another interface. The relay listens on exactly the addresses published: its listeners are read out of the published records, and they open together or not at all, because an address published and not listened on would produce a printer that is discovered and cannot be reached. With no preferred link-local address, no AAAA is published and print jobs are accepted over IPv4 only. This departs on purpose from RFC 6762 §6.2, which asks for every address valid on the interface: every interface has a link-local address (RFC 4291 §2.1), so every IPv6 device on the link has one to connect from; a link-local address cannot be reached from beyond the link; and it is recognised by its prefix rather than by a platform flag (the finding). The addresses are read once, at startup, as the IPv4 address is. If a published address is gone when the listeners next open, the service logs why, says goodbye and stops, to be restarted; RFC 6762 §8.4 asks a host to announce its new addresses instead, and this does not. What happens to a listener whose address disappears while it is open is not established. (Corrected 2026-10-07 by Claude, Claude Opus 5.5: from the commit that built this row, 2c93864 of 2026-10-01, until this date the code did not do what the sentence beginning "If a published address is gone" says. It logged that it was stopping and ended that one interface's listeners. The rest of the service ran on: it said no goodbye, and it went on answering with the addresses published and nothing listening on them. A part of the service that fails now stops the whole service, which says goodbye as it ends. Neither the fault nor the correction has been seen on a machine; see the finding.) (Note, 2026-10-08, by Claude, Claude Opus 5.5: the correction has now been seen on a machine. A listener was made to fail by another program holding the port on the client-side address, not by an address that had gone; the service logged why, said goodbye and stopped, within about three seconds of starting. An address that has gone is still not tried. See the finding.)
REQ-ADV-022 MUST The service says what its own names do not have, so that a client gets a definite negative and not silence. It owns two names, its host name and its service instance name, having probed for both with type ANY (REQ-ADV-023). When a question in class IN or ANY (REQ-ADV-025) asks for a type that one of those names has no record of, the service answers with an NSEC record for that name in the Answer section, as RFC 6762 §6.1 requires. The NSEC lists the types the name does have: A, and AAAA when one is published (REQ-ADV-021), for the host name; TXT and SRV for the instance name. It is in the restricted form of §6.1: its next domain name is its own name, and it has one type bitmap. A question for type NSEC itself is answered the same way. A question for type ANY is answered with the records at the name and no NSEC. The service-type names (REQ-ADV-001, REQ-ADV-002) are shared with other devices, and RFC 6762 §6 forbids a negative answer for a shared name, so a question for a type the service does not have there is not answered. The service gives no such answer while it is probing, while it offers nothing (REQ-LIF-006), or after a conflict (REQ-ADV-024). A response that carries an address record of the host, in any section, when the host has no address record of the other type, also carries the host's NSEC in the Additional section (RFC 6762 §6.2). For this service that is a host with an A record and no AAAA. RFC 6762 §6.1 also permits an NSEC beside any other unique answer, and the service does not send one there. The NSEC for the host name has a TTL of 120 seconds and the one for the instance name 4,500 (RFC 6762 §6.1, §10), and both have the cache-flush bit set. A legacy unicast answer (REQ-ADV-017) carries the same NSEC with its TTL capped and the bit clear; what a legacy resolver does with it has not been measured. An NSEC is never announced and never proposed in a probe, and the goodbye (REQ-LIF-003) retracts both. Both are listed in the startup log (REQ-OBS-003). Measured on 2026-10-02 on the test machine, running commit 64e8fc2 (the finding): an iPhone asked for types 65, AAAA and A at the service's host name twelve times, and each time was answered within 7 milliseconds with the NSEC, listing A and AAAA, TTL 120, cache-flush bit set, beside the two address records; it printed a page 63 seconds after one of those answers; the goodbye was captured retracting both NSEC records; and the log held no conflict. Seen only in tests, with a fake transport, and not on a network: the instance name's NSEC as an answer, the NSEC as an additional (the test machine's host name has both address types), and the legacy unicast answer. In the same runs, twice, the iPhone reached the printer and sent no job. The same failure is on record from 2026-10-01 on a build that sent no NSEC; its cause is not established, and the finding says why it is not attributed to this requirement. Measured earlier, and the reason for this requirement: on 2026-09-29 HTTPS and AAAA questions for the service's host name, from two devices, went unanswered (the finding). Measured on 2026-09-06 with the experiment tool SecretPrinter.Respond6: an iPhone sent IPv4 SYNs to port 631 seventy milliseconds after a response carrying an A record. Whether that response carried an NSEC is not recorded, and whether an NSEC plays any part was not measured (open question 7). (Corrected 2026-10-01 by Claude, Claude Opus 5.5: this sentence said iOS accepted the NSEC, which was not measured.) (Note, 2026-10-02, by Claude, Claude Opus 5.5: SecretPrinter.Respond6 was deleted on 2026-10-02; section 12 says where its source is.) (Rewritten 2026-10-01 by Claude, Claude Opus 5.5: until then this row asked only for an NSEC in a response carrying an A record for a name with no AAAA. It did not cover a question for a type one of the service's names lacks, which RFC 6762 §6.1 requires an answer to, and it did not say where the record goes, what it lists, its TTL, or when it is not sent.) (Updated 2026-10-02 by Claude, Claude Opus 5.5: from 2026-10-01 until then this row said the behaviour was not yet measured on hardware, that nothing was marked with this requirement, and that the coverage matrix reported it NOT IMPLEMENTED.)
REQ-ADV-023 MUST Before announcing on a client interface, at startup and again before restoring an advertisement after any withdrawal, the service probes for the names it advertises as unique (the service instance name and the host name), as RFC 6762 §8.1 describes. It sends three queries for type ANY, 250 ms apart, each carrying in its Authority Section the records it proposes to publish, over both IPv4 and IPv6. It announces only if no conflict (REQ-ADV-024) arrives within 250 ms of the third. Both transports are used because on the network this was built on, IPv4 mDNS from part of the client network did not reach the service's machine. A simultaneous probe from another device is resolved as RFC 6762 §8.2 describes. The probes ask for multicast answers, although RFC 6762 §8.1 says they should ask for unicast ones: the service shares port 5353 with the Windows DNS Client (REQ-ADV-014), and which of two sockets sharing a port receives a unicast answer has not been established, so a unicast answer could be missed.
REQ-ADV-024 MUST A conflict is any response from another device that carries a record for one of those names that the service would not itself publish: a different type, or the same type with different data. Identical records are not a conflict (RFC 6762 §9). An NSEC record for one of those names is judged by the types it lists. One that lists exactly the types the service publishes at that name is not a conflict, whoever sent it; that is also how the service's own NSEC (REQ-ADV-022), heard back, is recognised. One that lists anything else, or that is not in the restricted form of RFC 6762 §6.1, is a conflict. Its next domain name is not compared, because §6.1 says a receiver should ignore that field. On a conflict, found while probing or at any time after announcing, the service offers nothing, as REQ-LIF-006 describes. It stays that way until restarted, even while the printer is reachable, and does not pick another name. The log gives the name, the record type and the address of the device that answered, so the operator can choose a different name. Any device on the client network can cause this by answering for the service's names. mDNS has no authentication, and this is accepted for a home network. (Added 2026-10-01 by Claude, Claude Opus 5.5: the four sentences about NSEC records. Until commit 838e877 the code treated any NSEC for one of those names as a conflict, and this row did not mention them.)
REQ-ADV-025 MUST The service answers a question only when its class, read without the unicast-response bit (RFC 6762 §5.4), is IN (1) or ANY (255). Every record the service sends is in class IN, and RFC 6762 §6 lets a record answer a question only when their classes agree or the question's class is ANY. A question in any other class is ignored, as a question for a name the service does not hold is (REQ-ADV-012), and it is not taken for a competing probe (REQ-ADV-023). A legacy unicast answer (REQ-ADV-017) repeats each question in the class it was asked in, as RFC 6762 §6.7 requires. Until 2026-10-01 the class was not read; see the finding. (Note, 2026-10-13, by Claude, Claude Opus 5.5: the bit is also read now, and decides only whether an answer goes by unicast (REQ-ADV-028).)
REQ-ADV-026 MUST The service does not answer with a record that the query already carries. RFC 6762 §7.1 says a responder "MUST NOT answer a Multicast DNS query if the answer it would give is already included in the Answer Section with an RR TTL at least half the correct value". A record that the query's Answer section holds with the same name, the same type, class IN and the same data, at a TTL of at least half the TTL the service publishes it with, is left out of the answer. The class is read without the cache-flush bit, which RFC 6762 §10.2 says a querier must not set there. At less than half the record is sent, with its own TTL, as §7.1 requires. When every answer to a query is left out, nothing is sent, and the first line of the stop summary counts such queries apart from queries about other names. The Additional section is chosen from the answers that are sent; known answers are not looked for among the additionals, which §7.1 does not ask for. The rule applies to a legacy unicast querier (REQ-ADV-017) as to any other. A query marked truncated, whose known answers go on in the packets after it (§7.2), is judged on its own packet and answered at once, not held back for the rest. (Added 2026-10-10 by Claude, Claude Opus 5.5. Until then the service answered such a query; on a network on 2026-10-02 it did so 8, 1 and 11 times in three runs. Measured against the code by tests; not yet run on a network. See the finding.) (Updated later on 2026-10-10 by Claude, Claude Opus 5.5: run that day on a network, once, for 9 minutes 41 seconds on the test machine in place of FIOS-STB-01. 26 of 134 queries seen carried every answer and were not answered, and an iPhone printed a page through it. See the finding of the run.) (Note, 2026-10-11, by Claude, Claude Opus 5.5: a build with this change ran on FIOS-STB-01 for 22 hours 46 minutes 56 seconds, from 2026-10-10 to 2026-10-11. Its stop summary counted 9,365 queries seen: 163 answered, 9,138 for other services, and 64 that carried every answer and were not answered. See the finding.) (Note, later still on 2026-10-13, by Claude, Claude Opus 5.5: a truncated query whose answer takes the random wait of REQ-ADV-029 is answered after that wait, 20 to 120 ms after it arrived, and not at once. The known answers in the packets after it are still not read before it is answered. §6 asks 400 to 500 ms for such a query, which is not done.)
REQ-ADV-027 MUST The service does not multicast a record on a client adapter until at least one second has passed since it last multicast that record there. RFC 6762 §6 says a responder "MUST NOT (except in the one special case of answering probe queries) multicast a record on a given interface until at least one second has elapsed since the last time that record was multicast on that particular interface". An answer leaves out every record, answer or additional, that the service multicast on that adapter less than a second before. When no answer is left, nothing is sent, and the first line of the stop summary counts such queries apart from the others. The RFC gives the reason that is enough: "A querier that did not receive and cache the previous transmission will retry its request and receive a subsequent response." An announcement (REQ-ADV-001) and a goodbye (REQ-LIF-003) wait instead until the second is up, never longer than a second, so that each still carries every record. A goodbye counts as a multicast of the records it retracts. An answer to a probe, which is a query carrying records in its Authority Section as REQ-ADV-023 describes, waits until 250 ms have passed since any record in it was last multicast on that adapter, and leaves nothing out: §6 relaxes the second to that "when responding via multicast to a probe". Any query with a record in its Authority Section is answered that way; whether it is a real probe is not judged. An adapter's IPv4 side and its IPv6 side are one interface for this rule, as the service already treats them for §6.2 (REQ-ADV-022): a record multicast over IPv4 is not multicast over IPv6 within the second, nor the reverse. So when a client asks the same question over both within a second, the second copy gets no answer with those records; each copy is still answered only over the transport it arrived on (REQ-ADV-018). A unicast answer to a legacy querier (REQ-ADV-017) is not a multicast: it is not limited and is not counted as one. The service's own probes (REQ-ADV-023) are queries, timed by §8.1, and are neither limited nor counted. A send that fails is not counted as a multicast. Elapsed time is read from a clock that does not go backwards, so a change to the system time cannot hold records back. (Added 2026-10-12 by Claude, Claude Opus 5.5. Until then the service kept no record of what it had sent: on a network on 2026-10-02, three of its answers in one run followed the one before by 0.22, 0.34 and 0.67 seconds, repeating the same records. Measured against the code by tests; not yet run on a network. See the finding.) (Updated later on 2026-10-12 by Claude, Claude Opus 5.5: run that day on a network, once, for 9 minutes 59 seconds on the test machine in place of FIOS-STB-01. 4 of 116 queries seen would have repeated records multicast less than a second before and were not answered, 28 carried every answer already, and an iPhone printed a page through it. Which questions the 4 were is not known. See the finding of the run.) (Note, later on 2026-10-13, by Claude, Claude Opus 5.5: an answer sent by unicast because a question asked for one (REQ-ADV-028) is not a multicast either, and is neither limited nor recorded. The records a probe asks for by unicast go by unicast at once, without the 250 ms wait.) (Note, later still on 2026-10-13, by Claude, Claude Opus 5.5: an answer that takes the random wait of REQ-ADV-029 is judged by this rule after the wait, at the moment it is sent. An answer to a probe takes no random wait. After its 250 ms wait, nothing is sent if meanwhile the printer has been withdrawn, a conflict heard or a probe begun; until that day it was sent regardless.)
REQ-ADV-028 MUST The service answers by unicast a question that asks for a unicast answer, as RFC 6762 §5.4 says a responder should: "When receiving a question with the unicast-response bit set, a responder SHOULD usually respond with a unicast packet directed back to the querier. However, if the responder has not multicast that record recently (within one quarter of its TTL), then the responder SHOULD instead multicast the response so as to keep all the peer caches up to date, and to permit passive conflict detection." The choice is made record by record. A record that a question with the unicast-response bit asks for, and no question without it, goes by unicast to the querier when the service multicast it on that client adapter, over either transport, less than a quarter of its TTL before; every other record goes by multicast, under REQ-ADV-027. Every record the service publishes has a TTL of at least 120 seconds, a quarter of which is longer than a second, so a record asked for by unicast alone is never held back by REQ-ADV-027: if it was multicast within the second, it goes by unicast. The unicast answer is made as the multicast one would be, because §5.4 says "Unicast replies are subject to all the same packet generation rules as multicast replies": identifier 0, no question, TTLs and cache-flush bits as published. Its additionals are those of its own answers, less any record the multicast answer to the same query carries. It goes to the querier's address and port, through the interface the query arrived on, and only to an address on the network the query arrived from (REQ-SEC-017); from any other address the records go by multicast instead. It is not a multicast: REQ-ADV-027 neither holds it back nor records it. A probe from another device (REQ-ADV-023) whose question asks for a unicast answer gets one at once, whether or not the records were multicast recently, because §5.4 says "the responder should always generate the requested unicast response"; the multicast announcement §5.4 says it "may also send" is not sent. A legacy querier (REQ-ADV-017) is answered as before, and the service's own probes still ask for multicast answers (REQ-ADV-023). The first line of the stop summary says how many of the queries served were answered by unicast because they asked for it. An IPv4 answer sent this way takes the IP TTL that REQ-ADV-013's note says is not established. (Added 2026-10-13 by Claude, Claude Opus 5.5. Until then such a question, from port 5353, was answered by multicast. Measured against the code by tests; not yet run on a network. §5.4 says a querier "sending its initial batch of questions immediately on wake from sleep or interface activation SHOULD set the unicast-response bit in those questions", and not otherwise, so how often this happens on a network is not known. See the finding.) (Updated later on 2026-10-13 by Claude, Claude Opus 5.5: run that day on a network, once, on the test machine in place of FIOS-STB-01, for about 13 minutes 26 seconds in all. Of 1,324 queries seen, 31 were answered, and 29 of those by unicast because they asked for it; none was held back within a second, and an iPhone printed a page. Which devices asked for unicast is not known. See the finding of the run.) (Note, 2026-10-14, by Claude, Claude Opus 5.5: this row is about questions that arrive at the mDNS group. A question sent by unicast straight to port 5353, which RFC 6762 §5.5 says should be answered as this row says, has not been seen answered; see Known problems.)
REQ-ADV-029 MUST The service waits a random time before an answer that other devices may be sending too, as RFC 6762 §6 asks: "In any case where there may be multiple responses, such as queries where the answer is a member of a shared resource record set, each responder SHOULD delay its response by a random amount of time selected with uniform random distribution in the range 20-120 ms." And §6.3: "for query messages containing more than one question, all (non-defensive) answers SHOULD be randomly delayed in the range 20-120 ms". An answer waits when it holds a shared record, one the service publishes without the cache-flush bit, which are its three PTR records, at the three shared names REQ-ADV-012 lists; or when the query holds more than one question, however many of them the service answers. The wait is a whole number of milliseconds from 20 to 120, both included, each as likely as any other, drawn anew for each answer. An answer to a query of one question that holds only records the service claims alone (REQ-ADV-023) goes at once: §6 says a responder that will be the only one to answer "SHOULD NOT impose any random delay before responding". So does an answer to a probe (REQ-ADV-023), however long REQ-ADV-027 makes it wait: "In the special case of answering probe queries ... a Multicast DNS responder MUST respond quickly." A query with nothing for the service to answer does not wait. The wait applies however the answer goes: by multicast; by unicast because a question asked for one (REQ-ADV-028), since §5.4 says "Unicast replies are subject to all the same packet generation rules as multicast replies, including ... randomized delays"; or to a legacy querier (REQ-ADV-017). It comes before the rest of the answer is decided, so that the one-second rule of REQ-ADV-027 and the choice of unicast of REQ-ADV-028 are judged at the moment the answer is sent. After it, and after an answer to a probe has waited for REQ-ADV-027's 250 ms, nothing more is sent if meanwhile the printer has been withdrawn (REQ-LIF-006), a conflict heard (REQ-ADV-024) or a probe begun (REQ-ADV-023); a probe's unicast answer, sent before its wait, has gone by then. While an answer waits, the service reads no other query: queries that arrive meanwhile wait to be read, so when several that each take the wait arrive together, their answers go one after another, and a later one can go more than 120 ms after it was asked. A legacy query from an address REQ-SEC-017 refuses waits before it is refused. Two things §6 asks are not done: a query marked truncated, whose known answers go on in the packets after it (§7.2), is not given the 400 to 500 ms §6 asks for, so that they can arrive (REQ-ADV-026 judges it on its own packet); and answers are not held for up to 500 ms so that several go in one message, which §6 says a responder on Ethernet "SHOULD have the capability of" doing. The first line of the stop summary says how many of the queries served were answered after a random wait. (Added 2026-10-13 by Claude, Claude Opus 5.5. Until then every answer went as soon as it was made: on a network on 2026-09-29 an answer to a browse came about a millisecond after it. Measured against the code by tests; not yet run on a network. See the finding.) (Updated 2026-10-14 by Claude, Claude Opus 5.5: run on a network once, on FIOS-STB-01, from 16:08:29Z to 16:40:48Z that day, in a build made there. Of 831 queries seen, 17 were answered, and every one of the 17 after a random wait; a capture on the client adapter timed three of them at 62.5, 103.0 and 114.6 ms after their questions. None was held back within a second, and an iPhone printed a page. No two queries that each took the wait arrived together, so an answer held behind another's wait was not seen. See the finding of the run.)
REQ-ADV-030 MUST The service reads a response for records about the names it claims (REQ-ADV-024), while probing and at any time after, only when the response was sent to the mDNS group, 224.0.0.251 or ff02::fb, as the destination address that IP_PKTINFO or IPV6_PKTINFO reports shows, and came from UDP port 5353. A response sent by unicast, one from any other port, and one whose destination is not known are silently ignored: nothing is logged, counted or kept, and a record in one is not a conflict. RFC 6762 §6 says "Multicast DNS implementations MUST silently ignore any Multicast DNS responses they receive where the source UDP port is not 5353", and that a querier "MUST only accept unicast responses if they answer a recently sent query (e.g., sent within the last two seconds) that explicitly requested unicast responses" and "MUST silently ignore all other unicast responses". The service's only questions on the client network are its probes, which ask for multicast answers (REQ-ADV-023), so no unicast response answers one of them; a unicast to port 5353 on this machine may also be meant for the Windows DNS Client, which shares the port (REQ-ADV-014). Until 2026-10-27 a response that arrived on a client interface was read for conflicts whatever its destination and source port; releases up to 0.5.0 do so. (Added 2026-10-27 by Claude, Claude Opus 5.5. Measured against the code by tests; see docs/findings/2026-10-27-the-conflict-check-takes-only-a-multicast-response-from-port-5353.md. Run once on a network that evening, on FIOS-STB-01 in a build of 0b51fcc: its probe at startup came back clear and a page printed; release 0.6.0, published on 2026-10-30, is the first to carry it. See docs/findings/2026-10-27-the-build-of-0b51fcc-was-installed-on-fios-stb-01.md. Until then this note said "not yet run on a network". Changed 2026-10-30 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.6.0: it said "no release carries it". Made exact later that day, once 0.6.0 had been published: it said "0.6.0, the sixth version meant as a release, is the first to carry it". See docs/findings/2026-10-30-the-sixth-release-was-published-and-installed-on-fios-stb-01.md.)

5. Requirements: resolution (RES)

How the service finds the real printer.

ID Level Requirement
REQ-RES-001 MUST The printer's address is resolved by mDNS query on the printer-side interface at the time a connection is relayed.
REQ-RES-002 MUST NOT The printer's IP address is read from configuration as the primary means of locating it.
REQ-RES-003 MUST The printer is identified in configuration by mDNS service instance name, which is stable across DHCP address changes.
REQ-RES-004 MAY A resolved address is cached, for no longer than the DNS TTL of the record it came from.
REQ-RES-005 MUST A resolution failure causes the relay attempt to fail with a logged, specific error. It never falls back to a guessed or remembered-indefinitely address.
REQ-RES-006 MUST Resolution queries are sent only on the configured printer-side interface.
REQ-RES-007 MUST The address and port used to connect to the printer come from resolving the configured _ipps._tcp instance, on the printer-side interface, when a connection is relayed. The printer's capabilities come from the TXT record of the configured _ipp._tcp instance. Neither service supplies what the other is specified to supply. The service resolves both instances at startup, before advertising anything. If either cannot be resolved it logs the instance that did not answer and asks again as REQ-LIF-008 describes, advertising nothing meanwhile.
REQ-RES-008 MUST The service holds a printer-reachability state derived from mDNS on the printer-side interface: resolution by the same query path a relayed job uses, and, while it holds the printer unreachable, the printer's own records heard there without being asked (REQ-RES-011). It is never derived from the adapter being reported up, from its address being present, or from a multicast membership being listed. While the printer is reachable, the service reconfirms it on the cache-maintenance schedule of RFC 6762 §5.2: a query at 80-82% of the record's TTL, then 85-87%, 90-92% and 95-97% if unanswered, holding the printer unreachable once the record reaches 100% of its lifetime with no answer. While the printer is unreachable, it re-queries under the same section's continuous-querying rule - the first two queries at least one second apart, each interval at least double the last, capped at 60 minutes. An answer obtained by a resolution performed because a job arrived resets the schedule like any other answer, unless it is no newer than the answer already held or its lifetime is already over; a job's resolution that goes unanswered is not counted, because the reconfirmations already decide when the record has gone. Concurrent jobs share one in-flight query rather than issuing one apiece, whether or not it is answered. Measured: an adapter that had left 224.0.0.251 continued to list it, and an adapter reported up with a working unicast path returned no multicast answers (docs/findings/2026-09-19-the-printer-side-multicast-membership-is-lost.md). Interface state has been observed wrong in both directions; resolution has not. (Note, 2026-10-10, by Claude, Claude Opus 5.5: the continuous-querying sequence is now started over when the printer-side adapter is usable again, as REQ-RES-010 says. The state is still never derived from the adapter: only an answer makes the printer reachable.) (Changed 2026-10-22 by Claude, Claude Opus 5.5, with REQ-RES-011: the first sentence said "derived from mDNS resolution on the printer-side interface - the same query path a relayed job uses." The state is still never derived from the adapter: only what the printer itself sends makes it reachable.) (Note, 2026-10-26, by Claude, Claude Opus 5.5: the TTL this schedule runs on is the answer's lifetime, which since REQ-RES-013 is never more than 120 seconds.)
REQ-RES-009 MUST The service reopens its printer-side mDNS socket before each question it puts to a printer it holds unreachable, and before each startup attempt after the first. Reopening examines the printer adapter again and, if the adapter is usable, opens a new socket joined to 224.0.0.251 on the adapter's current address, with a new resolver on it, then closes the old socket. If the adapter is not usable or the socket cannot be opened, the old socket is kept, and the reason is logged when it first appears and when it changes. Measured: on 2026-09-25 the resolver socket's membership of 224.0.0.251 was found gone after the printer-side Wi-Fi had been out for ten hours and then for three minutes more, and the adapter reconnecting did not bring it back; a new socket joined at once (docs/findings/2026-09-25-a-reconnect-did-not-restore-the-membership.md).
REQ-RES-010 MUST From the end of its startup until it stops, the service examines the printer-side adapter every 5 seconds, by the rule REQ-LIF-008 uses to decide whether it is usable. When the adapter is usable after having been seen not usable, or is usable with a different address or index than when last seen, and the printer is held unreachable, the service asks the printer at once and starts the continuous-querying sequence of REQ-RES-008 again from one second. It logs that in one line, as information, naming the interface as found. While the printer is held reachable, nothing changes and nothing is logged. The adapter's state never makes the printer reachable: only the printer does, by an answer or by its own records heard (REQ-RES-011). A failure to examine the adapter is logged when it begins, when it changes and when it comes back after an examination that worked, and is taken for no change either way. A drop shorter than 5 seconds can fall between two examinations and not be seen. The startup wait of REQ-LIF-008 keeps its own sequence. RFC 6762 does not require this: §5.4 speaks of a querier sending "its initial batch of questions immediately on wake from sleep or interface activation", and §10.3 has a host whose hardware indicates a change of connectivity "take this information into account in its Multicast DNS cache management strategy". Decided by Edwin West on 2026-10-10, after release 0.1.0, in three losses on FIOS-STB-01, offered the printer 13, 38 and about 12 minutes after a script of his, not part of SecretPrinter, first saw the printer's port answer again. It does not make every loss shorter, because it moves when each later question falls. Worked out from the code against 0.1.0's record, and not run: in the second of those losses it could have offered the printer within a minute of the Wi-Fi being reconnected, if the printer answered mDNS then; in the first, where the printer's port stayed closed for more than two hours after the Wi-Fi was back, it would have offered the printer 26 to 35 minutes later than 0.1.0 did (docs/findings/2026-10-10-the-printer-is-asked-again-when-its-network-comes-back.md). (Note, 2026-10-11, by Claude, Claude Opus 5.5: run on a network. Overnight on FIOS-STB-01 the printer was lost 10 times in 21 hours 31 minutes. In the three losses where the printer-side Wi-Fi had been disconnected, the line came 1 to 3 seconds after Windows reported the Wi-Fi connected again, the printer answered at once, and it was offered again within 6 seconds of the reconnect. Each reconnect was made by a script of Edwin West's, not part of SecretPrinter; Windows did not reconnect by itself. Worked out from the code, none of the ten losses was made longer. No reconnect happened while the printer was held reachable, so that case is shown by tests only (docs/findings/2026-10-11-the-start-over-ran-overnight-on-fios-stb-01.md).) (Note, 2026-10-12, by Claude, Claude Opus 5.5: run again in release 0.2.0 on FIOS-STB-01. Four times in its first 23 hours 32 minutes the line came 2 to 5 seconds after Windows reported the Wi-Fi connected again, reconnected by the same script, and the printer was held reachable in that second or the next. Windows did not reconnect it by itself (docs/findings/2026-10-11-the-second-release-was-published-and-installed-on-fios-stb-01.md, status note of 2026-10-12).) (Note, 2026-10-13, by Claude, Claude Opus 5.5: seen on the test machine for the first time, in a build of 70f01c3 run from a console. Its printer-side Wi-Fi was turned off by hand and did not come back by itself; the printer was withdrawn and, when the Wi-Fi was reconnected 1 hour 27 minutes later, the line came about 3 seconds after the command that reconnected it and the printer was offered again 3 seconds after the line (docs/findings/2026-10-13-twenty-nine-answers-went-by-unicast-on-a-network.md).) (Changed 2026-10-22 by Claude, Claude Opus 5.5, with REQ-RES-011: it said "only an answer does".)
REQ-RES-011 MUST While the service holds the printer unreachable per REQ-RES-008, the printer's own mDNS records heard on the printer-side interface while no question of the service's is waiting for them make it reachable as an answer does, without waiting for the next question: an announcement as the printer starts (RFC 6762 §8.3), or an answer it multicasts to another device. RFC 6762 §6: "Multicast DNS queriers receiving Multicast DNS responses do not care what question elicited the response; they care only that the information in the response is true and accurate." They are taken only from a response that arrived on the printer-side interface (REQ-RES-006), was sent to the mDNS group, as the destination address that IP_PKTINFO reports shows, and came from UDP port 5353, because §6 says a querier "MUST silently ignore all other unicast responses" and "MUST silently ignore any Multicast DNS responses they receive where the source UDP port is not 5353"; never from a question, whose Answer Section lists another device's known answers (§7.1); and only from the Answer and Additional sections, class IN. They make the printer reachable when they include the configured _ipps._tcp instance's SRV record and an A record for the host that SRV names, in one datagram or several, each within the TTL it was heard with; the answer's lifetime is the shorter of the two left, and less than a second left is no answer. A record with a TTL of 0 is a goodbye (§10.1): it is never taken, by this path or by a lookup, and it forgets the same record if one is held. At most 16 address records are held: those whose TTL has run out are forgotten first, then the one heard longest ago. While the printer is held reachable such records change nothing, and a goodbye never withdraws it. The recovery is logged as information: Printer reachable again: it was heard on the printer-side interface without being asked (an announcement, or its answer to another device). Decided by Edwin West on 2026-10-22, after the printer was seen on 2026-10-21 to announce itself eight times in the two minutes after it was switched on, while the service kept what arrived only for a question that was waiting, and its questions after a long outage are an hour apart (docs/findings/2026-10-21-the-printer-announces-itself-when-it-starts.md). (Added 2026-10-22 by Claude, Claude Opus 5.5. Measured against the code by tests; the wiring in ServiceHost.RunAsync is run by no test. See docs/findings/2026-10-22-the-service-hears-the-printer-announce-itself.md. Run once on a network that evening, on FIOS-STB-01 in a build from source: the printer, switched off for about 16 minutes and on again, was heard and offered again no more than about 40 seconds after it was switched on, when the service's next question was about 3 minutes away; release 0.5.0, published on 2026-10-25, is the first to carry it. See docs/findings/2026-10-22-the-service-heard-the-printer-come-back-on-fios-stb-01.md. Until then this note said "not yet run on a network". Changed 2026-10-25 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.5.0: it said "no release carries it yet". Made exact later that day, once 0.5.0 had been published: it said "0.5.0, the fifth version meant as a release, is the first to carry it". See docs/findings/2026-10-25-the-fifth-release-was-published-and-installed-on-fios-stb-01.md.) (Note, 2026-10-26, by Claude, Claude Opus 5.5: since REQ-RES-013 an SRV or address record heard this way is held for its TTL but never for more than 120 seconds, so "within the TTL it was heard with" now means within that.)
REQ-RES-012 MUST A lookup on the printer-side interface takes its answer only from a response that was sent to the mDNS group, as the destination address that IP_PKTINFO reports shows, and came from UDP port 5353. A response sent by unicast, one from any other port, and one whose destination is not known are ignored. RFC 6762 §6 says a querier "MUST only accept unicast responses if they answer a recently sent query (e.g., sent within the last two seconds) that explicitly requested unicast responses" and "MUST silently ignore all other unicast responses", and that "Multicast DNS implementations MUST silently ignore any Multicast DNS responses they receive where the source UDP port is not 5353". No question the service puts to the printer sets the unicast-response bit (§5.4), so no unicast response answers one. The printer's records heard while no lookup is waiting are held to the same two rules by REQ-RES-011. Until 2026-10-26 a lookup took a response that arrived on the printer-side interface whatever its destination and source port; releases up to 0.5.0 do so. (Added 2026-10-26 by Claude, Claude Opus 5.5. Measured against the code by tests; see docs/findings/2026-10-26-a-lookup-takes-only-a-multicast-response-from-port-5353.md. Run once on a network later that day, on FIOS-STB-01 in a build of de1d171: both startup lookups were answered in the same second, so the printer answered by multicast from port 5353, and a page printed; release 0.6.0, published on 2026-10-30, is the first to carry it. See docs/findings/2026-10-26-the-build-of-de1d171-was-installed-on-fios-stb-01.md. Until then this note said "not yet run on a network". Changed 2026-10-30 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.6.0: it said "no release carries it". Made exact later that day, once 0.6.0 had been published: it said "0.6.0, the sixth version meant as a release, is the first to carry it". See docs/findings/2026-10-30-the-sixth-release-was-published-and-installed-on-fios-stb-01.md.)
REQ-RES-013 MUST No answer about the printer is believed for longer than 120 seconds, whatever TTL its records carry. A lookup's answer holds for the shorter of the TTLs of the SRV and A records it is made of, and never more than 120 seconds; the printer's SRV and address records heard while no lookup is waiting (REQ-RES-011) are each held for their TTL, and never more than 120 seconds. That lifetime is the one REQ-RES-004's cache and REQ-RES-008's schedule run on. RFC 6762 §10: "As a general rule, the recommended TTL value for Multicast DNS resource records with a host name as the resource record's name (e.g., A, AAAA, HINFO) or a host name contained within the resource record's rdata (e.g., SRV, reverse mapping PTR record) SHOULD be 120 seconds." When a lookup's answer is cut to 120 seconds, the TTL its records came with is kept, and the startup log line that names the answer ends TTL 120s, capped from that TTL. The TXT record's TTL does not count towards the lifetime. Until 2026-10-26 an answer held for its TTL however long, so a device on the printer-side network that answered one of the service's questions with a very long TTL would have had its address reused by print jobs, and the printer held reachable, for most of that time before the service asked again; releases up to 0.5.0 do so. Read from the code; not seen. On 2026-10-21 the service's questions to the printer came 96.7 to 98.7 seconds apart, each answered at once, which fits 80 to 82% of an answer lifetime of 120 seconds, and such an answer is not changed. (Added 2026-10-26 by Claude, Claude Opus 5.5. Measured against the code by tests; see docs/findings/2026-10-26-an-answer-is-believed-for-at-most-120-seconds.md. Run once on a network later that day, on FIOS-STB-01 in a build of de1d171: both startup answers had a lifetime of 120 seconds and nothing was capped, and a page printed; release 0.6.0, published on 2026-10-30, is the first to carry it. See docs/findings/2026-10-26-the-build-of-de1d171-was-installed-on-fios-stb-01.md. Until then this note said "not yet run on a network". Changed 2026-10-30 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.6.0: it said "no release carries it". Made exact later that day, once 0.6.0 had been published: it said "0.6.0, the sixth version meant as a release, is the first to carry it". See docs/findings/2026-10-30-the-sixth-release-was-published-and-installed-on-fios-stb-01.md.)

6. Requirements: relay (PXY)

How print jobs are moved.

ID Level Requirement
REQ-PXY-001 MUST The service accepts TCP connections on the advertised IPP port, on configured client interfaces only.
REQ-PXY-002 MUST Accepted connections are relayed to the resolved printer address on the printer's IPP port.
REQ-PXY-003 MUST NOT The service inspects, parses, modifies, or interprets the IPP payload. Bytes are relayed unchanged in both directions.
REQ-PXY-004 MUST NOT The service writes any part of a print job to disk, at any point, including on error.
REQ-PXY-005 MUST Buffers holding job data are bounded in size; the service streams rather than accumulating a whole job in memory.
REQ-PXY-006 MUST Closing either side of a relayed connection closes the other.
REQ-PXY-007 MUST Connections that cannot be established to the printer are refused promptly, with a logged reason, rather than left hanging.
REQ-PXY-008 MUST Concurrent relayed connections are supported; one client must not block another.
REQ-PXY-009 MUST Log entries about a relayed connection record endpoints, byte counts, and timing — never job content. (Note, 2026-10-07, by Claude, Claude Opus 5.5: one case has no ending entry. A relayed connection that is still open when the service stops, or when it withdraws the printer (REQ-LIF-006), is cut by the service, and nothing is logged for its end: its acceptance and its start are in the log, and its byte counts and its duration are not. The relay reports failures and does not report its own cancellation. Seen in the logs of 2026-10-02, 2026-10-04 and 2026-10-06, and recorded in the findings of those days.)
REQ-PXY-010 MUST The connection to the printer is TLS from its first byte. No part of a print job is sent to the printer over an unencrypted connection.
REQ-PXY-011 MUST NOT The service parses, interprets, or emits HTTP in order to establish that TLS connection. It does not use the in-band Upgrade: TLS/1.0 mechanism, so nothing in the relay reads the traffic it carries.
REQ-PXY-012 MUST A failed TLS handshake or a failed certificate check ends the relayed connection with a logged reason, before any job byte reaches the printer. There is no unencrypted fallback. (Note, 2026-10-07, by Claude, Claude Opus 5.5: a handshake that settles on a protocol older than TLS 1.2 is ended the same way. Windows chooses the protocol; the service reads what was chosen and abandons anything but TLS 1.2 or TLS 1.3 before a job byte is sent. The code has done this since 2026-09-17, and this row did not say it.)

7. Requirements: configuration (CFG)

ID Level Requirement
REQ-CFG-001 MUST Configuration is explicit. The service applies no default that changes what is advertised or where traffic is sent.
REQ-CFG-002 MUST Configuration names client interfaces and the printer interface separately and unambiguously.
REQ-CFG-003 MUST Configuration is validated at startup. Any inconsistency causes the service to fail to start, with a message naming the offending setting.
REQ-CFG-004 MUST Interface names given in configuration are resolved to addresses at startup, and the resolution is logged.
REQ-CFG-005 MUST NOT The service starts in a partially working state. Either every configured client interface is usable, or startup fails. The printer-side interface is the one exception, defined by REQ-LIF-008: while it is not usable the service offers nothing at all, which is withdrawn rather than partially working. (Note, 2026-10-07, by Claude, Claude Opus 5.5: one thing a client interface needs is not checked when the configuration is loaded, which is IPv6. The service joins ff02::fb on every client interface (REQ-ADV-018), and it first tries to after the printer has answered. Read from the code and never run: with IPv6 switched off on a client adapter, the service would wait for the printer as usual and then stop with an error that names the adapter.)
REQ-CFG-006 MUST The service refuses to start if a client interface and the printer interface resolve to the same interface.
REQ-CFG-007 MUST The printer's expected certificate fingerprint is explicit configuration: the SHA-256 hash of the DER-encoded certificate, written as exactly 64 hexadecimal digits in either case, with no separators and no whitespace. The service refuses to start without it or with a value in any other form, and names the setting when it refuses.
REQ-CFG-008 MUST The instance name of the printer's _ipps._tcp service is explicit configuration, separate from the instance name of its _ipp._tcp service. The service does not derive either name from the other. It refuses to start without the _ipps._tcp instance name, and names the setting when it refuses.

8. Requirements: security and trust (SEC)

ID Level Requirement
REQ-SEC-001 MUST NOT The service forwards, reflects, or relays any mDNS traffic between networks. It answers queries with its own advertisement, and with NSEC records it builds from that advertisement to say which record types its own names have (REQ-ADV-022), and nothing else. (Amended 2026-10-01 by Claude, Claude Opus 5.5: this said "with its own advertisement and nothing else". An NSEC record is built from the advertisement and is not one of its records, so that sentence would have stopped being true when the service began sending them.) One kind of answer also repeats part of the question it answers: an answer sent by unicast to a legacy querier carries that query's identifier and its question, as RFC 6762 §6.7 requires (REQ-ADV-017, REQ-ADV-025). They are written again from the values the service read, and go to the device that sent them, on the network they came from. (Added 2026-10-07 by Claude, Claude Opus 5.5: until then this row said "and nothing else" with no word on this, and the marker in MdnsResponder.cs said "no byte of a received packet is ever re-emitted". The marker is corrected in the same commit.) (Note, 2026-10-13, by Claude, Claude Opus 5.5: until this date "on the network they came from" held only for a querier that gave its own address, because the answer went to whatever address the query gave. It now goes only to an address on the network the query arrived from (REQ-SEC-017).)
REQ-SEC-002 MUST NOT The service exposes any service type other than those it is configured to proxy. Non-printing services on the printer network remain invisible from the client network.
REQ-SEC-003 MUST NOT The service opens, listens on, or relays any port other than those required for the configured print services and mDNS.
REQ-SEC-004 MUST NOT The service creates, modifies, or deletes firewall rules. Required rules are documented for the operator to apply.
REQ-SEC-005 MUST NOT The service reads or writes the Windows registry other than as required by the service control manager to run as a service.
REQ-SEC-006 MUST The service runs with the least privilege sufficient to bind its ports and join multicast groups, and documents what that is.
REQ-SEC-007 MUST NOT The service enables IP forwarding, alters the routing table, or otherwise changes host network configuration.
REQ-SEC-008 MUST NOT The service transmits anything to any host outside the two configured local networks. There is no telemetry, no update check, and no analytics. (Note, 2026-10-13, by Claude, Claude Opus 5.5: until this date one thing could be sent outside them: an answer by unicast to a legacy query whose source address had been forged to one on neither network, which Windows would route through a router. Measured against the code with a fake transport; not seen on a network. Corrected by REQ-SEC-017; see the finding.)
REQ-SEC-009 MUST Every dependency is either the .NET base class library or a project inside this repository. Packages outside that require explicit documentation and justification in this file; see Dependencies.
REQ-SEC-010 MUST The documentation states, prominently, that print job data passes through the proxy host.
REQ-SEC-011 MUST NOT The service acts as a general-purpose proxy, router, or NAT for any traffic.
REQ-SEC-012 MUST Relayed connections are accepted only from the configured client networks; connections from elsewhere are refused and logged. Over IPv6 that means link-local clients on the client interface itself: fe80::/10, arriving with that interface's scope, which is checked separately because a network match cannot see scopes. A relay given no permitted network refuses every connection. (Note, 2026-10-07, by Claude, Claude Opus 5.5: over IPv4, the client network is worked out from the client interface's address and is not read from its subnet mask. It is every address that shares the first three numbers of that address, or, when the address begins with 10, every address that begins with 10. On a network whose mask is anything else, that is more addresses, or fewer, than the network holds. The listener is bound to the client interface's own address in every case (REQ-PXY-001).) (Note, 2026-10-13, by Claude, Claude Opus 5.5: the same IPv4 network, worked out by the same rule, now also decides where an answer may be sent by unicast (REQ-SEC-017). The rule moved, unchanged, from ServiceHost.cs to src/SecretPrinter.Mdns/ClientNetwork.cs, which both use, so that the two cannot come to disagree.)
REQ-SEC-013 MUST The printer's certificate is compared against the configured SHA-256 fingerprint on every connection, and the connection is abandoned if it does not match. No other hash algorithm is accepted in its place. The certificate is self-signed, so no chain and no hostname check can stand in for this. (Note, 2026-10-07, by Claude, Claude Opus 5.5: the certificate's dates are not read. A certificate that matches the fingerprint is accepted after its expiry date, as Edwin West decided on 2026-09-15: the fingerprint names one exact certificate, and refusing it on a date would add only a day on which printing stops. The reason is in src/SecretPrinter.Proxy/CertificatePin.cs; this row did not say it.)
REQ-SEC-014 MUST NOT Any configuration setting, command-line flag, build switch, or environment variable disables or weakens that comparison. There is no permissive mode.
REQ-SEC-015 MUST The documentation states, prominently, that print jobs travel unencrypted on the client network and are encrypted only between the proxy and the printer.
REQ-SEC-016 MUST NOT The probe, SecretPrinter.Probe, which a release includes beside the service (REQ-DIST-011), starts another program, reads or writes the Windows registry, makes an HTTP request, or writes a file. It does open a socket, and only its own assembly can: it puts its questions over UDP to the network of the interface address it is given, and reads the replies. (Added 2026-10-06 by Claude, Claude Opus 5.5. The probe has been in the release folder since 2026-10-04, and until this requirement nothing in this specification or its tests covered it; see the finding.)
REQ-SEC-017 MUST NOT The service sends an mDNS answer by unicast to an address that is not on the network the query arrived from. Over IPv4 that network is the client network as the relay works it out from the client interface's address (REQ-SEC-012). Over IPv6 the address must be a link-local address carrying the scope of the interface the query arrived on, compared with that interface's IPv6 index; a link-local address with no scope is refused, because which link it is on cannot be told. A legacy unicast query (REQ-ADV-017) from any other address is not answered, and the first line of the stop summary counts such queries apart from the others. A query about a name the service does not hold is counted as that, whatever its address. An answer sent by multicast is not affected: it goes to the group on the link the query arrived on. The check is needed because the service sets the adapter its multicasts leave by and not the one a unicast datagram leaves by, which Windows chooses from its routing table (Microsoft documents IP_MULTICAST_IF as the outgoing interface "for sending IPv4 multicast traffic", and IP_UNICAST_IF, which the service does not set, for other traffic). RFC 6762 §5.5 asks the same of a query sent by unicast: responders "SHOULD check that the source address in the query packet matches the local subnet for that link (or, in the case of IPv6, the source address has an on-link prefix) and silently ignore the packet if not". (Added 2026-10-13 by Claude, Claude Opus 5.5. Until then a legacy query was answered by unicast to whatever address it gave, so a device on the client network that forged the source address of a query could have had the service's answer sent out of the printer-side adapter, or through a router to an address on neither network. Releases 0.1.0 and 0.2.0 do that. Measured against the code by tests with a fake transport; not seen on a network, and whether Windows passes on a query whose source address is not on the network it arrived on has not been measured. See the finding.) (Note, later on 2026-10-13, by Claude, Claude Opus 5.5: the same check governs an answer sent by unicast because a question asked for one (REQ-ADV-028). From an address it refuses, those records go by multicast instead, and the query is not counted as refused.) (Note, later on 2026-10-13, by Claude, Claude Opus 5.5: run on a network once, with REQ-ADV-028. 29 answers went by unicast, each to an address the check allowed, and none was refused; no legacy querier is known to have asked. Whether the IPv6 source address of a received datagram carries its scope on Windows is still not established. See the finding of the run.)
REQ-SEC-018 MUST The probe, SecretPrinter.Probe, keeps a reply only when it was sent from UDP port 5353 and carries the identifier of the query the probe sent in that round. The probe asks from a port the operating system chooses, so a responder answers it as a legacy querier, by unicast (RFC 6762 §6.7), and every question it asks sets the unicast-response bit. RFC 6762 §6 says "The source UDP port in all Multicast DNS responses MUST be 5353", that implementations "MUST silently ignore any Multicast DNS responses they receive where the source UDP port is not 5353", and that a querier "MUST only accept unicast responses if they answer a recently sent query (e.g., sent within the last two seconds) that explicitly requested unicast responses"; §6.7 says a legacy unicast response "MUST repeat the query ID and the question given in the query message". A datagram from any other port is not read, and a response carrying another identifier is not kept. Nothing is sent back for either; the probe prints a line for each, saying it was ignored and why, because it is a diagnostic that reports what came back. The probe listens in each round for the time --timeout gives, 5 seconds unless set; §6 gives two seconds as an example, and this was not changed. Neither check makes a reply trustworthy: the probe sends its query, identifier included, to the mDNS group, so any device on that network can see it and answer from port 5353 as a printer would, and mDNS gives no way to tell them apart. (Added 2026-10-28 by Claude, Claude Opus 5.5. Until then the probe kept every DNS response that reached its socket, from any port and with any identifier; every release up to 0.5.0 does so. Measured against the code by tests, and run once on the printer-side network from the development machine, where the printer's two replies were kept and nothing was ignored. See the finding.)

9. Requirements: lifecycle and observability (LIF, OBS)

ID Level Requirement
REQ-LIF-001 MUST The service starts and stops cleanly under the Windows service control manager. (Note, 2026-10-14, by Claude, Claude Opus 5.5: not when Windows shut down or restarted, until this date. The stop never began then, and the process ended with an exception nothing caught; see REQ-LIF-009.)
REQ-LIF-002 MUST On shutdown the service leaves multicast groups, closes listening sockets, and terminates in-flight relays. (Note, 2026-10-14, by Claude, Claude Opus 5.5: at a Windows shutdown or restart the service did none of this itself until this date; Windows released its sockets when the process ended. See REQ-LIF-009.) (Note, 2026-10-20, by Claude, Claude Opus 5.5: until this date a client connection accepted in the moment the service stopped, or withdrew the printer (REQ-LIF-006), could be left open: its relay was never started, so nothing closed it, and nothing was logged. Found by reading the code; never seen on a machine. See the finding.)
REQ-LIF-003 MUST On shutdown the service sends mDNS goodbye records (TTL 0) for everything it advertised, so clients drop it promptly. (Note, 2026-10-07, by Claude, Claude Opus 5.5: the goodbye is sent over IPv4 only, as the announcements are (REQ-ADV-001). Probes go out over both (REQ-ADV-023), and a question is answered over the transport it arrived on (REQ-ADV-018). An iPhone has been seen keeping the printer listed after a goodbye, and on another day dropping it within about three seconds; see docs/operating.md. Until this note the fact was in that document and not in this one.) (Note, 2026-10-14, by Claude, Claude Opus 5.5: at a Windows shutdown or restart no goodbye was sent until this date, although the code claimed one; see REQ-LIF-009.)
REQ-LIF-004 MUST Fatal configuration or binding errors cause a fast, loud failure — never silent partial operation. (Note, 2026-10-07, by Claude, Claude Opus 5.5, rewritten later the same day: until this date two things here were not so. A part of the running service that failed left the other parts running, which is the silent partial operation this row forbids; and under the Windows service control manager a failure that came after the configuration had been accepted was loud in the log and was not reported to Windows. A part that fails now stops the whole service, which is tested. As a Windows service the process then ends with exit code 4, which has not been run under Windows. See Known problems and the finding.) (Note, 2026-10-08, by Claude, Claude Opus 5.5: run under Windows that day, on an install made from the published pre-release, with a listener made to fail on purpose. The service logged why, said goodbye and ended its process within about three seconds of starting; Windows showed it STOPPED with error 1067 and recorded event 7034, "terminated unexpectedly". See the finding.)
REQ-LIF-005 MUST Transient network errors are logged and retried, and do not terminate the service. (Corrected 2026-10-07 by Claude, Claude Opus 5.5: until this date the mDNS responder did not meet this in two ways. A socket error while receiving a datagram was counted and not logged. A socket error while sending an answer ended the responder's receive loop for good, with nothing logged, and the service then answered no query until it was restarted. Both are now logged, once for each different error, and the loop goes on. Neither has been seen on a machine; see the finding.)
REQ-LIF-006 MUST While the printer is unreachable per REQ-RES-008, the service stops accepting new client connections, stops answering mDNS queries about itself, and withdraws its advertisement with goodbye records as REQ-LIF-003 requires on shutdown. It resumes all three when the printer answers again, or is heard again without being asked (REQ-RES-011). Each change is logged once, with what was observed. The service does not offer a printer it has established it cannot reach. Measured: on 2026-09-20 the printer-side WLAN dropped at 06:49:38Z and the service, which correctly diagnosed the adapter as down, went on advertising and accepting jobs for nine hours; twelve jobs were accepted after the diagnosis and all twelve failed. (Note, 2026-10-07, by Claude, Claude Opus 5.5: there is one case in which it does not resume. If the probe or the announcement cannot be sent when the printer answers again, because the socket reports an error, the service logs that the printer could not be offered, and offers nothing until the printer is lost and found again or the service is restarted. Read from the code; not seen on a network.) (Changed 2026-10-22 by Claude, Claude Opus 5.5, with REQ-RES-011: it said "when the printer answers again".)
REQ-LIF-007 MUST Under the Windows service control manager, a configuration the service refuses is reported to the control manager as a failure to start, not left to time out, and the reason is in the log. Measured: on 2026-09-18 and 2026-09-19 nine refusals, each logged at once with its reason, each reached Windows as error 1053, "did not respond to the start or control request in a timely fashion". The code returned before it had called ServiceBase.Run, so the control manager was never answered. See the finding.
REQ-LIF-008 MUST At startup the service does not refuse to start because the printer-side interface is unusable or the printer does not answer. It waits, offering nothing to the client network: no advertisement, no answer to any query, and no listener, as while withdrawn under REQ-LIF-006, with no goodbye records because nothing was announced. The printer-side adapter must exist by name when the configuration is loaded; its state is examined locally at a fixed interval, and it is usable once it is up, holds exactly one IPv4 address, that address is outside 169.254.0.0/16, and the platform does not report it tentative, deprecated or invalid. Then the printer is asked on the REQ-RES-008 schedule for an unreachable printer until both instances resolve. The adapter wait is logged when it begins, when its reason changes and when it ends; the printer wait when the printer first fails to answer and when it answers. A misspelled printer instance name is indistinguishable from a printer that is switched off, so it waits as well, and the log says so. Decided 2026-09-22, after nine refusals caused by the printer-side adapter being down at startup (docs/findings/2026-09-22-a-refused-start-is-reported-as-a-timeout.md).
REQ-LIF-009 MUST When Windows shuts down or restarts, the service stops as it does for a stop request (REQ-LIF-001): it cancels its work and waits for it, so that the goodbye is sent (REQ-LIF-003), its sockets are closed (REQ-LIF-002) and the summary is written, and it logs that the stop came from Windows shutting down. It does not ask Windows for more time then. .NET's ServiceBase marks a service stop-pending before it hands it a stop request, but hands it a shutdown with the service still marked running; RequestAdditionalTime throws unless the service is marked pending, and what the shutdown handler throws ends the process. How long Windows waits for a service at a shutdown is set on each machine by WaitToKillServiceTimeout, 5000 milliseconds on FIOS-STB-01; nothing here asks for more. (Added 2026-10-14 by Claude, Claude Opus 5.5. Until then the shutdown handler called the stop handler, which asked for more time before stopping anything, so at every shutdown or restart of Windows since the first commit the stop never began and the process ended with an exception nothing caught. Releases 0.1.0 and 0.2.0 do this. Seen on FIOS-STB-01 that morning, while nothing was offered. The exception was measured on Windows by a test before the correction, and the correction by the same test and by two that read the compiled service; it has not been run at a real restart. See the finding.) (Note, 2026-10-14, by Claude, Claude Opus 5.5: run at a real restart later that day, on FIOS-STB-01, in a build of 8663e5c made there, with the printer offered. The service logged that Windows was shutting down, that it no longer accepted print jobs, that it had sent the goodbye records, its summary and SecretPrinter stopped., all within the same second, and Windows recorded no application error. A second restart, made by Windows to finish installing an update, came while the service waited at startup, and the service stopped with nothing to retract, since nothing had been announced (REQ-LIF-008). The goodbye was not captured on the wire. See the finding of the run.)
REQ-OBS-001 MUST Startup logs list every interface in use, its resolved address, and its role.
REQ-OBS-002 MUST Every advertisement published is logged, including the full TXT record set.
REQ-OBS-003 MUST The operator can determine, from logs alone, exactly what the service told the client network.
REQ-OBS-004 MUST NOT Logs contain print job content, at any log level.
REQ-OBS-005 SHOULD The documentation notes that the service's log, and what the listening tool prints, hold addresses and the names of devices seen on the network, so operators handle them accordingly. (Reworded 2026-10-07 by Claude, Claude Opus 5.5: this read "Logs note that observed mDNS traffic may contain device names, so operators handle captures accordingly." No log line says so and none ever did. The note is in the listening tool's README, which is the evidence docs/verification.md has named for this row, and in docs/operating.md, which is now named with it.)
REQ-OBS-006 MUST When a relayed connection fails, the logged reason names which peer the failure came from and whether it happened while reading or writing — and carries nothing derived from job content.
REQ-OBS-007 MUST The shutdown summary reports queries seen and answered for each transport separately, naming both even when a count is zero, so an operator can tell whether anything was served over IPv6.
REQ-OBS-008 MUST Startup logs record the fingerprint the service will require of the printer, and each relayed connection logs the TLS protocol negotiated with it, so an operator can confirm from logs alone that the job went encrypted and to which device.
REQ-OBS-009 MUST The service writes its log to a file when the operator names one on the command line, and refuses to run under the Windows service control manager unless they do — a service has no console, so without a file it would report nothing anywhere. The path has no default, the service creates no folder to hold it, and the file is opened before configuration is read so that a refusal to start is recorded in it.
REQ-OBS-010 MUST Every log entry occupies exactly one line. Control characters in a message are escaped rather than written, so text learned from the network cannot insert a line break and forge an entry.
REQ-OBS-011 MUST At every start, the first entry the service logs, before it reads its configuration, names the program and gives the version stamped in it: the text Windows reports as the program file's ProductVersion, which in a release is the version, a +, and the commit the release was built from. A start that the configuration refuses carries it too. If the program carries no stamp, the entry says so. (Added 2026-10-18 by Claude, Claude Opus 5.5. Releases 0.1.0, 0.2.0 and 0.3.0 do not log their version.)

10. Requirements: build and distribution (DIST)

ID Level Requirement
REQ-DIST-001 MUST The project targets .NET 10 (LTS) and builds with the published SDK version recorded in global.json.
REQ-DIST-002 MUST The solution builds with TreatWarningsAsErrors and produces zero warnings.
REQ-DIST-003 MUST Continuous integration builds the solution, runs all tests, and runs the specification checker described in Section 11.
REQ-DIST-004 MUST Release binaries are signed with Azure Trusted Signing. (Microsoft has since renamed that service Artifact Signing; this requirement means the same service. Note added 2026-10-04 by Claude, Claude Opus 5.5.)
REQ-DIST-005 MUST The release documentation states how to verify a signature, and that unsigned binaries are not official releases.
REQ-DIST-006 MUST Every release is a tagged commit with a changelog entry.
REQ-DIST-007 MUST Analyzer suppressions are justified in place, in source, with a written reason. Blanket suppression files are not used.
REQ-DIST-008 MUST Requirements that cannot be satisfied by code are recorded in docs/verification.md, each naming at least one artifact by repository-relative path.
REQ-DIST-009 MUST A requirement counts as tested only when a test carrying its identifier is recorded as having passed in a test-results file. A marker on a test that was skipped or failed does not count.
REQ-DIST-010 MUST Test results are accepted only when the assemblies they were produced against are byte-identical to those being checked. Results describing code that has since been rebuilt are refused.
REQ-DIST-011 MUST Release artifacts run without the .NET SDK or a separately installed .NET runtime. The service, and every tool the operating documentation tells someone using a release to run, are published self-contained.

11. How to validate this README against the code

A specification that is only prose is a specification nobody checks. This one is machine-checkable.

The mechanism

Step 1 — Requirements carry identifiers. Every row in Sections 4–10 has an ID like REQ-PXY-003. These are stable; they are never renumbered. A retired requirement is marked withdrawn, not deleted.

Step 2 — Code declares which requirement it implements. Types and methods are marked with an attribute from SecretPrinter.Spec. So is a whole assembly, for a claim about what it does not contain: the service's, and the probe's under tools/. From src/SecretPrinter.Proxy/IppRelay.cs:

[Requirement("REQ-PXY-003",
    "Copies bytes verbatim in both directions. Nothing here reads, branches on, or alters payload content.")]
public async Task<RelayOutcome> RelayOneAsync(IDuplexConnection client, CancellationToken cancellationToken)

Step 3 — Tests declare which requirement they verify. From tests/SecretPrinter.Proxy.Tests/IppRelayTests.cs:

[TestCase("Bytes reach the printer exactly as the client sent them")]
[Requirement("REQ-PXY-003")]
public static void Payload_reaches_the_printer_unchanged()

[TestCase] is this repository's own, from tests/SecretPrinter.TestKit. No test framework is referenced. (Both examples replaced 2026-10-07 by Claude, Claude Opus 5.5. They showed a class and a test that are not in the repository, the marker sat on a class where the real one sits on a method, and the test carried [Fact], the attribute of a test framework this project does not use.)

Step 3a — Requirements that cannot be code are evidenced instead. Some requirements are properties of the build or release process rather than of any type or method: REQ-DIST-004 (release binaries are signed) can never carry an attribute. Those are recorded in docs/verification.md, one row per requirement, each naming the artifacts that satisfy it. A row has this shape; the real row for this requirement is longer:

| REQ-DIST-004 | .github/workflows/release.yml | The sign step invokes Azure Trusted Signing. |

SpecCheck treats such a row as coverage only after confirming every named path exists. Evidence pointing at a renamed or deleted file is reported as EVIDENCE BROKEN and fails the check, so a claim cannot rot unnoticed. Entries naming no artifact are ignored, which leaves the requirement uncovered.

Evidence is permitted for any requirement, because deciding which requirements are "really" about code is not a judgement a tool should make. The safeguard is visibility: requirements covered this way are reported as OK (evidence) and counted separately in every run, so the proportion resting on evidence rather than tests is always in view.

Step 3b — Test markers only count when the test actually ran. A [Requirement] attribute on a test is compiled-in metadata: it exists in the assembly whether or not the test ever executed. A test that skips on every machine would otherwise count as full coverage.

The test suites therefore write a results file recording what executed:

PASS	REQ-ADV-013	SecretPrinter.Mdns.Tests.MdnsSocketTests.Open_sets_ttl_255
SKIP	REQ-CFG-006	SecretPrinter.Mdns.Tests.MdnsSocketTests.ResolveAll_rejects_shared_interface

SpecCheck reads it via --test-results and counts a requirement as tested only when a test carrying its identifier PASSED. Anything else is reported as TEST DID NOT RUN, with the reason, and fails the check.

This was not a hypothetical. REQ-CFG-006 needs a network adapter holding two IPv4 addresses; its test skipped on both the development machine and the target machine, and the matrix reported it OK on both until this was added.

Step 3c — Results must describe the build being checked. A results file records the module version id of every SecretPrinter assembly the run exercised. Builds are deterministic, so that id is a function of content and changes exactly when the code does. (Note, 2026-10-07, by Claude, Claude Opus 5.5: since 2026-10-04 the version and the commit the clone is on are stamped into every assembly, so the id also changes when either of those does, with no change to the code. After moving a clone to another commit, build and run the suites again before running the check.)

SpecCheck compares those fingerprints against the assemblies it scans and refuses any file produced against different code:

TEST RESULTS DO NOT DESCRIBE THIS BUILD:
  SecretPrinter.Advertising has been rebuilt since these results were produced

This also began as a real mistake rather than a hypothetical: a results file left over from an earlier run was passed to SpecCheck and counted as coverage for code it did not describe. The common form is editing code, rebuilding, and re-running the check without re-running the tests.

Running SpecCheck without --test-results is permitted but never silent: the summary reports Test execution: NOT VERIFIED and the result line says so.

Running it. Continuous integration (.github/workflows/ci.yml) discovers the test suites, runs each one, and passes every results file to the checker. Doing it by hand means one --test-results flag per suite, which went wrong on most attempts during development and always in the direction of reporting less coverage than existed.

Until every requirement is covered, CI fails. That is intended: the check reports every binding requirement that has no implementation, naming each one in the coverage matrix it writes to the run summary, and a green badge over an incomplete specification would be the exact overstatement this repository exists to avoid. An earlier version of this paragraph stated a fixed count of such requirements. It was correct when written and wrong within days, which is why the number is now read from the matrix instead of asserted here. The consequence is worth stating plainly - while the build is red for a known reason, it is less useful at signalling a new problem, so read which step failed rather than trusting the colour.

(2026-10-04: the last four binding requirements without coverage, REQ-DIST-004, 005, 006 and 011, were covered by evidence that day, and the check passed on the development machine at the commit that added this note. Whether CI is green is for its run page to say, not this paragraph. Note added by Claude, Claude Opus 5.5.)

Step 4 — A tool checks the correspondence. tools/SecretPrinter.SpecCheck parses the requirement tables out of this README, reflects over the built assemblies, and produces a coverage matrix. The four lines below show the four kinds of result. They are an illustration and not today's matrix, in which REQ-ADV-005 and REQ-ADV-016 both read OK:

REQ-PXY-003   MUST NOT  impl: IppRelay                  test: Relay_does_not_alter~  OK
REQ-ADV-005   MUST NOT  impl: AdvertisementBuilder      test: (none)                 MISSING TEST
REQ-ADV-016   SHOULD    impl: (none)                    test: (none)                 NOT IMPLEMENTED
REQ-DIST-002  MUST      impl: evidence: Directory.B~    test: (none)                 OK (evidence)

The tool exits non-zero when any MUST or MUST NOT requirement is covered neither by an implementation marker with a passing test nor by intact evidence, and CI fails on that. SHOULD requirements are reported but do not fail the build. (Reworded 2026-10-07 by Claude, Claude Opus 5.5: this said "lacks either an implementation marker or a test", which left out the requirements that rest on evidence.)

It also fails on the reverse error: an attribute in code citing an ID that does not appear in this README. Requirements and code cannot drift apart in either direction.

For an AI agent reviewing this repository

To check whether the code matches this document:

  1. Build, run the test suites, and then run the checker, from the repository root. On Windows, with the .NET 10 SDK:

    powershell -ExecutionPolicy Bypass -File .\run-tests.ps1
    powershell -ExecutionPolicy Bypass -File .\run-speccheck.ps1
    

    The first builds everything and runs every suite, writing a results file for each. The second hands those files to the checker, which reports which requirements are implemented, tested, evidenced, or none of these.

    The checker reads built assemblies, so the build has to come first. Until 2026-10-07 this step gave one command and nothing else: dotnet run --project tools/SecretPrinter.SpecCheck -- --readme README.md --evidence docs/verification.md --search . Run on a fresh clone, that builds the checker alone. Measured that day: it found 2 assemblies, reported no requirement as covered by code, and listed 79 binding gaps. That is a true report of a tree in which nothing has been built, and a false picture of the repository (the finding).

    On a machine with no IPv6, the tests that open an IPv6 socket skip, and the checker reports the requirements that only those tests cover as TEST DID NOT RUN. Measured on 2026-10-07 on Linux, in a workspace with no IPv6: nine tests skipped, and REQ-ADV-019 and REQ-ADV-020 read TEST DID NOT RUN. That workspace could not download the service's one package either, and compiled the service against the copy of that library inside the SDK. What the suites do on Linux with IPv6 has not been measured.

  2. For each requirement, read the marked implementation and judge whether it actually does what the requirement says. The tool proves a marker exists and that a test carrying it passed. It cannot prove the marker is honest, or that the test verifies anything meaningful. That judgement is the reviewer's.

  3. Pay particular attention to the MUST NOT requirements. Those are claims about what the software does not do, and they are verified by reading code and searching for absence — for example, confirming there is no file-write call anywhere in the relay path (REQ-PXY-004).

  4. Report any behaviour present in the code but absent from this document. Undocumented behaviour is a defect here even when it is harmless, because the entire premise of the project is that this document is complete.

Dependencies

The repository has exactly one declared package reference, which brings one transitive dependency with it. Both are listed, because "one package" would have been true of the csproj and false of what actually ships:

Package How Why
System.ServiceProcess.ServiceController 10.0.11 Declared by SecretPrinter.Service Provides ServiceBase, without which the program cannot register with the Windows service control manager. Published by Microsoft as part of .NET, but shipped out of band rather than in the base class library.
System.Diagnostics.EventLog 10.0.11 Pulled in by the above ServiceBase writes to the Windows Event Log when a service fails to start. SecretPrinter does not use it directly. (Note, 2026-10-07, by Claude, Claude Opus 5.5: not only then. SecretPrinter leaves ServiceBase.AutoLog at its default, which the header of src/SecretPrinter.Service/RefusedStartService.cs records as on. Microsoft's documentation says that with it on a service uses "the Application event log to report command failures, as well as state change information for Start, Stop, Pause, and Continue events", with the service's name as the source (ServiceBase.AutoLog, read 2026-10-07). So ServiceBase may write an entry at each start and stop of the service as well. Whether any such entry is written when the service runs as LocalService has not been measured.) (Note, 2026-10-08, by Claude, Claude Opus 5.5: read once. On a second machine, with the service running as LocalService, the Application log held no entry naming SecretPrinter in the half hour that covered one start of the service, a start that ended in a failure. The good start and the stop that followed were not read. See the finding.)

The alternative was hand-written interop against advapi32 - roughly 150 lines, untestable, in exactly the code path where a mistake means the printer is never retracted from clients' lists. That trade was judged the worse one.

A note relevant to REQ-SEC-005: the second package can write to the Windows Event Log, which is a registry-backed facility. SecretPrinter's own code references no registry type - tests read the compiled metadata of every assembly of the service, and of the probe, to confirm it - but the capability is present in the dependency graph via ServiceBase's own failure reporting. Stating that is more useful than a claim that reads as broader than it is. (Corrected 2026-10-06 by Claude, Claude Opus 5.5: this said "a test reads the compiled metadata of every shipped assembly". The probe is shipped too, and until that day no test read it; see the finding.)

A release also carries the .NET runtime. The release folder is published self-contained (REQ-DIST-011), so it holds its own copy of .NET, and the version of that copy is fixed when the folder is built. The folder the release workflow signed on 2026-10-04 carries .NET 10.0.12 (finding). Neither Windows Update nor installing .NET changes that copy. Microsoft's documentation says a self-contained application "doesn't roll forward to the latest available .NET security patch", and that its runtime "can only be upgraded by releasing a new version of the app" (.NET application publishing overview, read 2026-10-07). So a fix to .NET reaches an installation only in a new release of SecretPrinter. Which runtime a folder carries can be read from SecretPrinter.Service.runtimeconfig.json inside it. The runtime's files are Microsoft's and carry Microsoft's signatures; the release workflow checks those signatures and changes none of those files. (Paragraph added 2026-10-07 by Claude, Claude Opus 5.5.)

Everything else in this repository depends only on the base class library and on other projects here. REQ-SEC-009 is what keeps that true, and this table is what it means by documented.

Confirm it yourself:

Select-String -Path (Get-ChildItem -Recurse -Filter *.csproj) -Pattern 'PackageReference'

12. Repository layout

SecretPrinter/
├── README.md                          This specification
├── LICENSE                            MIT                                [done]
├── SECURITY.md                        How to report a vulnerability      [done]
├── CHANGELOG.md                       Per-release history                [done]
├── .gitignore                         Ignore rules, incl. captures       [done]
├── .gitattributes                     Line endings, fixed per file type  [done]
├── global.json                        Pinned SDK version                 [done]
├── Directory.Build.props              Shared build settings              [done]
├── SecretPrinter.slnx                                                    [done]
├── run-tests.ps1                      Build, run every suite, save results [done]
├── run-speccheck.ps1                  Run SpecCheck on those results     [done]
├── publish-release.ps1                Publish the release folder         [done]
│
├── docs/
│   ├── architecture.md                Design rationale in depth
│   ├── verification.md                Evidence for non-code requirements [done]
│   ├── operating.md                   Install, firewall, privileges      [done]
│   ├── threat-model.md                What this does and does not defend against
│   └── findings/                      Dated records of what was measured [done]
│                                      One file each, YYYY-MM-DD-subject.md
│
├── src/
│   ├── SecretPrinter.Spec/            The [Requirement] attribute        [done]
│   ├── SecretPrinter.Dns/             DNS wire format; no sockets        [built]
│   ├── SecretPrinter.Mdns/            mDNS socket layer                  [built]
│   ├── SecretPrinter.Advertising/     What to publish; no sockets        [built]
│   ├── SecretPrinter.Responder/       Answers queries; announces; goodbye [built]
│   ├── SecretPrinter.Resolution/      Finds the printer, on demand       [built]
│   ├── SecretPrinter.Configuration/   Loads and validates settings       [built]
│   ├── SecretPrinter.Proxy/           TCP relay; no file I/O at all      [built]
│   └── SecretPrinter.Service/         The host; wires everything up      [built]
│
├── tools/
│   ├── SecretPrinter.Probe/           Read what a printer advertises     [built]
│   ├── SecretPrinter.Listen/          Observe IPv4 mDNS; transmits nothing [built]
│   ├── SecretPrinter.Listen6/         Observe IPv6 mDNS; transmits nothing [built]
│   ├── SecretPrinter.Loop6/           Measure IPv6 multicast loopback    [built]
│   ├── SecretPrinter.Respond/         Advertise a fake printer (test)    [built]
│   └── SecretPrinter.SpecCheck/       README-to-code coverage matrix     [built]
│
├── tests/
│   ├── SecretPrinter.TestKit/         Shared harness, no NuGet deps      [built]
│   ├── SecretPrinter.Dns.Tests/       (see below)
│   ├── SecretPrinter.Mdns.Tests/                                         [built]
│   ├── SecretPrinter.Advertising.Tests/                                  [built]
│   ├── SecretPrinter.Responder.Tests/ Fake transport                     [built]
│   ├── SecretPrinter.Resolution.Tests/ Fake transport and clock          [built]
│   ├── SecretPrinter.Proxy.Tests/     In-memory streams                  [built]
│   ├── SecretPrinter.Configuration.Tests/ Fake adapters                  [built]
│   └── SecretPrinter.Service.Tests/   Includes assembly metadata scans   [built]
│
└── .github/workflows/
    ├── ci.yml                         Build, test, spec-check            [done]
    └── release.yml                    Build, sign, publish on a v tag    [done]

[done] and [built] mark what exists today. The rest is specified and not yet written.

SecretPrinter.Dns.Tests carries no mark because it does not exist yet. Until it does, SecretPrinter.Dns has no test project of its own; its types are used by the test kit and by the Advertising, Responder, Resolution and Service suites, which is not the same as being tested directly.

The tree does not list test counts or individual findings, because both change with almost every commit and a list that goes stale is a false statement. The current count is whatever run-tests.ps1 reports; the findings are the files in docs/findings/.

publish-release.ps1 produces the folder a release will be made from: the service and the probe, published for 64-bit Windows with the .NET runtime beside them, into one folder outside the repository. 0.1.0, published on 2026-10-08, is the first release; see CHANGELOG.md. 0.2.0, published on 2026-10-11, is the second. (Sentence added 2026-10-11 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.2.0, as "0.2.0 is the second version meant as a release."; made exact the same day, once it had been published.) 0.3.0, published on 2026-10-15, is the third. (Sentence added 2026-10-15 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.3.0, as "0.3.0 is the third version meant as a release."; made exact the same day, once it had been published.) 0.4.0, published on 2026-10-20, is the fourth. (Sentence added 2026-10-20 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.4.0, as "0.4.0 is the fourth version meant as a release."; made exact the same day, once it had been published.) 0.5.0, published on 2026-10-25, is the fifth. (Sentence added 2026-10-25 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.5.0, as "0.5.0 is the fifth version meant as a release."; made exact the same day, once it had been published.) 0.6.0, published on 2026-10-30, is the sixth. (Sentence added 2026-10-30 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.6.0, as "0.6.0 is the sixth version meant as a release."; made exact the same day, once it had been published.) (Note, 2026-10-07, by Claude, Claude Opus 5.5: 0.1.0-rc.3 is a pre-release for testing, not a release; see CHANGELOG.md. It was published that day.) (Corrected 2026-10-08 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.1.0: the sentence before the note of 2026-10-07 read "No release exists yet." Later the same day, once 0.1.0 had been published, "is the first version meant as a release" became "published on 2026-10-08, is the first release".) On 2026-10-04 a folder it made was run on a machine with no .NET installed, and an iPhone printed through it (finding). That run is the evidence for REQ-DIST-011 in docs/verification.md. (Paragraph, and the script's line in the tree, added 2026-10-03 by Claude, Claude Opus 5.5. Its last two sentences replaced 2026-10-04, when the run was made; they had said REQ-DIST-011 stayed uncovered until such a run was recorded.)

.github/workflows/release.yml turns a tag beginning with v into a release. It builds, runs every test, runs publish-release.ps1, signs SecretPrinter's own files in a job that runs in a GitHub environment set to require a person's approval, checks every signature, and publishes the zip only if the specification check passed. The version lives in one place, <Version> in Directory.Build.props, and the workflow refuses a tag that does not match it or that has no entry in CHANGELOG.md. It ran twice on 2026-10-04, for trial tags that are not releases: the first run failed before its signing job, and the second signed twelve files, whose signatures were read on a downloaded copy (finding). It ran a third time on 2026-10-07, for the pre-release 0.1.0-rc.3: all three jobs passed, the signing job after waiting for Edwin West's approval, and the job that publishes ran for the first time and published it (finding). On 2026-10-08 that pre-release was downloaded with a browser, checked, installed from nothing and printed through (finding). It ran a fourth time on 2026-10-08, for the tag v0.1.0: all three jobs passed, the signing job after Edwin West's approval, and the job that publishes published release 0.1.0, not marked as a pre-release, the first version it has published without a hyphen (finding). It ran a fifth time on 2026-10-11, for the tag v0.2.0: all three jobs passed, the signing job after Edwin West's approval, and release 0.2.0 was published, marked Latest (finding). (Sentence added 2026-10-11 by Claude, Claude Opus 5.5.) It ran a sixth time on 2026-10-15, for the tag v0.3.0: all three jobs passed, the signing job after Edwin West's approval, and release 0.3.0 was published, marked Latest (finding). (Sentence added 2026-10-15 by Claude, Claude Opus 5.5.) It ran a seventh time on 2026-10-20, for the tag v0.4.0: all three jobs passed, the signing job after Edwin West's approval, and release 0.4.0 was published, marked Latest. It was the first run of the step that names, in a section "Built with" of the release notes and on the run's page, the .NET SDK that built the release and the .NET runtime its folder carries (finding). (Sentences added 2026-10-20 by Claude, Claude Opus 5.5.) It ran an eighth time on 2026-10-25, for the tag v0.5.0: all three jobs passed, the signing job after Edwin West's approval, and release 0.5.0 was published, marked Latest. Its section "Built with" named the runtime Microsoft.NETCore.App 10.0.14, from Microsoft's out-of-band security update of that day, where the changelog entry, written before the build, wrongly said 10.0.13 was still the latest; a correction was added to the published notes (finding). (Sentences added 2026-10-25 by Claude, Claude Opus 5.5.) It ran a ninth time on 2026-10-30, for the tag v0.6.0: all three jobs passed, the signing job after Edwin West's approval, and release 0.6.0 was published, marked Latest, its section "Built with" naming .NET SDK 10.0.403 and the runtime Microsoft.NETCore.App 10.0.14 (finding). (Sentences added 2026-10-30 by Claude, Claude Opus 5.5.) (Rewritten 2026-10-08 by Claude, Claude Opus 5.5, in the commit that sets the version to 0.1.0. It said the workflow had run twice, and "No release has been published, and the job that publishes one has never run.", followed by a note of 2026-10-07 recording the third run and ending "No release has been published; a pre-release has." Later the same day, once 0.1.0 had been published, the last sentence, "0.1.0 is the first version meant as a release, and its tag, v0.1.0, runs the workflow for it.", was replaced by the one that begins "It ran a fourth time". This note said "the one before this note" until 2026-10-20, when Claude, Claude Opus 5.5, made it exact, the sentences on later runs having come between.) (Paragraph, the release.yml line in the tree and the [done] beside CHANGELOG.md added 2026-10-04 by Claude, Claude Opus 5.5, and corrected twice the same day as the workflow ran: it first said the workflow had never run, and then that nothing had been signed. Corrected 2026-10-07 by Claude, Claude Opus 5.5: it said the signing job "waits for a person's approval". That requirement is a setting of the GitHub environment, which is outside this repository, and whether the run of 2026-10-04 waited for an approval is not recorded. Added 2026-10-07 by Claude, Claude Opus 5.5: it is recorded. The public page of that run shows the environment approved by edwest19 on 2026-10-04, and the page of the run of 2026-10-07 shows the same for that day; see the finding linked above. The setting itself is still not read.)

On 2026-10-09 release 0.1.0 was installed on FIOS-STB-01 in place of a build from source, by the update steps of docs/operating.md, and an iPhone printed through it (finding). (Paragraph added 2026-10-09 by Claude, Claude Opus 5.5.) On 2026-10-10 a build of 5db9063, made on FIOS-STB-01 by publish-release.ps1 and not signed, replaced it there, to run overnight before a release (finding). (Sentence added 2026-10-10 by Claude, Claude Opus 5.5.) On 2026-10-11 release 0.2.0, downloaded there and checked, replaced that build by the same update steps with the signature check, and an iPhone printed through it (finding). (Sentence added 2026-10-11 by Claude, Claude Opus 5.5.) From 2026-10-14 unsigned builds made on FIOS-STB-01 ran there in its place, and on 2026-10-15 release 0.3.0, downloaded there and checked, replaced the last of them, a build of 8663e5c, by the same update steps with the signature check; an iPhone printed through it (finding). (Sentence added 2026-10-15 by Claude, Claude Opus 5.5.) On 2026-10-20 release 0.4.0, downloaded there and checked, replaced release 0.3.0 by the same update steps with the signature check, the first update from one release to the next; an iPhone printed through it (finding). (Sentence added 2026-10-20 by Claude, Claude Opus 5.5.) On 2026-10-22 a build of 5a291c4, made on FIOS-STB-01 and not signed, replaced it there, to run REQ-RES-011 on a network (finding), and on 2026-10-25 release 0.5.0, downloaded there and checked, replaced that build by the same update steps with the signature check; an iPhone printed through it (finding). (Sentences added 2026-10-25 by Claude, Claude Opus 5.5. The one on the build of 5a291c4 was not added on 2026-10-22, when it was installed.) On 2026-10-26 a build of de1d171, made on the development machine by publish-release.ps1 with SDK 10.0.403 so that it carries runtime 10.0.14, and not signed, was copied to FIOS-STB-01, checked there, and replaced release 0.5.0, to run REQ-RES-012 and REQ-RES-013 on a network; an iPhone printed through it (finding). (Sentence added 2026-10-26 by Claude, Claude Opus 5.5.) On 2026-10-27 a build of 0b51fcc, made the same way and not signed, replaced it there, to run REQ-ADV-030 on a network; an iPhone printed through it (finding). (Sentence added 2026-10-27 by Claude, Claude Opus 5.5.) On 2026-10-30 release 0.6.0, downloaded there and checked, replaced that build by the same update steps with the signature check; an iPhone read the printer's supply levels through it (finding). (Sentence added 2026-10-30 by Claude, Claude Opus 5.5.)

SecretPrinter.Listen6 and SecretPrinter.Loop6 are measurement tools written to answer one question each while IPv6 was being added; each one's header states its question and the finding that records the answer. Neither is part of the service.

A third, SecretPrinter.Respond6, was deleted on 2026-10-02. It advertised a printer over IPv6 mDNS only, with an A record, an NSEC and no AAAA record, standing in for the service before the service had an IPv6 socket. The service now answers over IPv6 (REQ-ADV-018) and sends the NSEC (REQ-ADV-022) itself. Two findings report runs made with the tool: 2026-09-06, the question it was written for, and 2026-09-29, where it was the second responder that the service found a name conflict with. Its source is in this repository's history: the last commit that holds tools/SecretPrinter.Respond6 is a10087d. Repeating either measurement needs the tool from that commit, or another responder that does the same. (Paragraph added 2026-10-02 by Claude, Claude Opus 5.5, in the commit that deleted the tool; until then the paragraph above listed it as a third measurement tool.)

Why the layering is what it is

SecretPrinter.Dns contains no socket code at all — it converts bytes to objects and back. SecretPrinter.Mdns owns sockets but knows nothing about printing. SecretPrinter.Proxy moves TCP bytes and knows nothing about mDNS. Only SecretPrinter.Service knows the whole story.

The separation exists so that the security-relevant claims can be checked locally. REQ-PXY-004 says no job data is written to disk; verifying that means reading one project, not the whole solution - and a test reads that project's compiled metadata and fails if it references any file-writing type at all. Likewise "could this ever publish the printer's address?" is answered by reading SecretPrinter.Advertising, which has no socket code and no way to learn the printer's address except from what it is handed.

13. Authorship and AI involvement

This project was written by an AI. That is the point of it, and it is stated here rather than discovered later.

What that means concretely:

  • Source files carry a header naming the model that wrote them and the person who directed the work. Three files carry none: LICENSE, which is the license's own text; global.json, whose format has no comments; and SecretPrinter.slnx, the solution file. The same claim is compiled into every assembly as metadata, from AuthoredBy in Directory.Build.props, so that it travels with a program separated from this repository. Until 2026-10-07 that metadata named Claude Opus 4.5 alone, although later models had written much of the code; it now names the three models named at the top of this document. (The last three sentences added 2026-10-07 by Claude, Claude Opus 5.5.)
  • Design decisions were made in conversation between a human and Claude. Where a decision was contested or uncertain, that is recorded in docs/ rather than presented as settled.
  • Claims in this document are backed by measurement where measurement was possible. docs/findings/ records what was actually observed, on real hardware, with the tools in tools/. Anyone can re-run them. One tool has since been deleted, and the two findings made with it need it from the repository's history (section 12). (That sentence added 2026-10-02 by Claude, Claude Opus 5.5.)
  • Where something was not verified, this document says so. An unverified claim labelled as verified would be worse than no claim.

What it does not mean:

  • It does not mean the code is correct. AI-written code has bugs like any other.
  • It does not mean a human is absent. Every merge is reviewed by a person, who is responsible for what ships.
  • It does not mean you should trust it because of who wrote it. Trust it, if at all, because the specification is complete, the code matches it, and you checked.

14. Open questions

Recorded here rather than resolved silently.

# Question Status
1 Does iOS require IPPS? Resolved: no, not for discovery. An iPhone listed a printer advertised with no IPPS service and no TLS. See findings. For printing the answer is different and was measured on 2026-09-15: the ET-3760 answers Get-Printer-Attributes in the clear but refuses Validate-Job with 426 Upgrade Required, so a job does not complete over plain IPP. The proxy therefore carries jobs to the printer over TLS; see findings and open question 8. (Corrected 2026-10-07 by Claude, Claude Opus 5.5: this still said "TLS is not deferred; it is the remaining blocker to printing." That stopped being true on 2026-09-17, the day of the first end-to-end print (finding).)
2 Can the service send mDNS responses that clients accept while another responder holds port 5353? Resolved: yes. Responses sent from a socket sharing 5353 with Dnscache were accepted by iOS, which listed the advertised printer. See findings.
3 What should the project be called? Resolved: SecretPrinter. The prefix is a deliberate joke shared across a family of open projects and means the opposite of what it says. Explained under About the name.
4 Is mopria-certified safe to relay? The bytes would be identical to the printer's, and the printer is certified — but the proxy is not the certified device. Currently forbidden by REQ-ADV-007. Revisit with evidence.
5 What privileges does the service actually need? Resolved: none beyond standard user. Measured on 2026-09-04 by running unelevated and confirming every bind, join and relay succeeded. Running as a Windows service under NT AUTHORITY\LocalService was measured on 2026-09-21 on FIOS-STB-01: under that account the service bound its sockets, joined both multicast groups, resolved the printer, answered discovery, opened TLS to the printer and relayed pages that printed. That was one machine. On a second, the test machine of the finding of 2026-10-04 and the finding of 2026-10-06, the service was registered under LocalService, started, and relayed pages that printed; the account of the running process was not read there. The dev box has no service registered. (Updated 2026-10-07 by Claude, Claude Opus 5.5: this said "That is one machine", which stopped being so on 2026-10-04.) The folder grant it runs with also lets it modify its own configuration file, which the service never does; that is recorded, not decided. (Until 2026-09-22 this entry said running under LocalService remained unmeasured, which had stopped being true on 2026-09-21.) See findings and findings.
6 How should the service register with Windows? Resolved: System.ServiceProcess.ServiceController is referenced for ServiceBase, documented under Dependencies as REQ-SEC-009 requires. Run with --service to register with the control manager, or without it as a console application.
7 Will iOS accept an A record delivered over IPv6 mDNS transport, and then connect over IPv4? Resolved: yes. Over ff02::fb, an iPhone was sent an mDNS response carrying an A record, and seventy milliseconds later it sent IPv4 SYNs to port 631. The responder was the experiment tool SecretPrinter.Respond6, which sends an NSEC denying AAAA with some of its answers and not with others; whether that response carried one is not recorded, and whether an NSEC played any part was not measured. (Note, 2026-10-02, by Claude, Claude Opus 5.5: the tool was deleted on 2026-10-02, and what is said of it here describes its last version; section 12 says where its source is.) IPv6 mDNS transport is specified as REQ-ADV-018 to REQ-ADV-020. Resolution, which talks to the printer, is unaffected by IPv6. The relay is not: REQ-ADV-021 publishes an AAAA record for each preferred link-local address of the client interface, and the relay listens on those addresses; open question 11 records which address an iPhone then used. See findings. (Corrected 2026-10-01 by Claude, Claude Opus 5.5: until then this entry said that the iPhone accepted the NSEC, which was not measured; that IPv6 was therefore mostly a transport addition to SecretPrinter.Mdns; and that resolution and relay were unaffected because REQ-ADV-021 forbade publishing an AAAA record. The last two stopped being true at commit 2c93864, on 2026-10-01, when REQ-ADV-021 was rewritten to publish link-local AAAA records and the relay began listening on them. This entry was not updated in that commit.)
8 Should the proxy originate TLS toward the printer? Open question 1 establishes that this printer will not accept a job without it, so printing depends on the answer. Resolved 2026-09-15: yes, and by implicit TLS on port 631, where the printer advertises _ipps._tcp and accepts a handshake from the first byte. The client side stays plaintext, which is a considered choice for a home LAN and is disclosed as the fourth item under Read this before installing. The certificate is self-signed — subject and issuer both CN=EPSON000000, the printer's host name with its low three bytes redacted as elsewhere in this repository — so it is pinned by fingerprint in configuration and checked on every connection, with no permissive mode. Trust-on-first-use was rejected because remembering a certificate means writing state to disk, and a test reads SecretPrinter.Proxy's compiled metadata and fails if it references any file-writing type at all. (An earlier wording here said "several tests" enforced that across "this project". There is one test, and it covers the proxy assembly. SecretPrinter.Service does write one file, the operator's log — see REQ-OBS-009.) Specified as REQ-PXY-010 to REQ-PXY-012, REQ-CFG-007, REQ-SEC-013 to REQ-SEC-015 and REQ-OBS-008. See findings.
9 How does someone using a release configure the service without developer tools? When this was asked, on 2026-09-16, configuring meant running the probe with dotnet run and measuring the certificate with a PowerShell command. Decided 2026-10-05 by Edwin West: by hand, following docs/operating.md, and release 0.1.0 has no configuration tool. The steps are: print the example configuration with SecretPrinter.Service.exe --print-example-config; name the adapters; copy the printer's two instance names from what SecretPrinter.Probe.exe prints; generate a UUID; and measure the printer's certificate fingerprint with one PowerShell command. Since 2026-10-04 the probe is a program in the release folder (REQ-DIST-011), so no step uses the dotnet command or needs the .NET SDK. The steps need the release folder and PowerShell, which Windows includes. What has been run: the example configuration printed, and the probe run, from a release folder on a machine with no .NET, on 2026-10-04 (finding); and the certificate command, on Windows 10, on 2026-09-15 (finding). The steps were followed from the first to the last on 2026-10-06, on a folder the release workflow had signed, and an iPhone printed through the configuration they produced (finding). Its limits, all in that finding: Edwin West ran commands that Claude took from docs/operating.md, and did not work from the document himself; it was one machine, one printer and one page; and only three lines of the example needed changing, because the example was written from this printer and the test machine's printer-side adapter has the name the example uses. The walk found three faults in docs/operating.md, corrected the same day: three commands that did not run as printed, a step that did not say where its values come from, and an instance name the probe prints twice. (Updated 2026-10-06 by Claude, Claude Opus 5.5: until then this said "What has not been done: following the steps from the first to the last on a release folder to make a configuration. In the runs of 2026-10-04 the configuration was a file copied from another machine.") Decided earlier, and now set aside. On 2026-09-16: a configuration tool, written in C# and reusing SecretPrinter.Dns, that would find the interfaces, the printer's instance names and its certificate and write the configuration file, with the operator confirming each before anything was written. On 2026-10-03: that the first release would wait for that tool. No such tool was written, and none is planned in this repository. Edwin West intends one for a separate project he calls SecretPrinterX, for a packaged form of SecretPrinter. This repository holds none of it. Two design points were open for the tool and were never answered: how it would read the certificate without a validation callback that accepts every certificate, which the TLS design rules out in shipped code; and whether it would count as shipped for the checks in SecurityClaimsTests, since it would open sockets and write a file. The second point has not gone away with the tool. The probe is in the release folder. It is not among the assemblies those checks read, and a comment in tests/SecretPrinter.Service.Tests/SecurityClaimsTests.cs says diagnostic tools are left out because "they are not installed". For the probe that stopped being true on 2026-10-04. Corrected 2026-10-06: the probe has a requirement of its own, REQ-SEC-016, and tests that read its assembly and the two it is built on. It is held to the checks it can meet (it starts no other program, touches no registry key, makes no HTTP request and writes no file) and not to the one it cannot, because it opens a UDP socket, which is its job. The comment is rewritten, and so are the markers that said "shipped" where they meant the service (finding). (Updated 2026-10-06 by Claude, Claude Opus 5.5: until then this ended "It is not yet corrected, and whether the probe should be held to those checks is not yet decided.") (Updated 2026-10-05 by Claude, Claude Opus 5.5: until then the question's second sentence read "Configuring today means running the probe with dotnet run and measuring the certificate with a PowerShell command, as docs/operating.md describes.", and this entry read "Decided 2026-09-16: a configuration tool, written in C# and reusing SecretPrinter.Dns so the repository keeps one DNS parser, will find the interfaces, the printer's instance names and its certificate, and write the configuration file, with the operator confirming each before anything is written. It will be built after printing over TLS works, so that it writes a configuration proven to print. Still open: how it reads the certificate without a validation callback that accepts every certificate, which the TLS design rules out in shipped code; and whether it counts as shipped for the checks in SecurityClaimsTests, since it opens sockets and writes a file.")
10 Which Windows versions and processor architectures do releases support? A self-contained release is published for a specific runtime and architecture, so REQ-DIST-011 cannot be met without an answer. Decided 2026-09-30 and 2026-10-03. Releases are built for 64-bit Windows on x64 processors only (win-x64), with no arm64 or x86 build; that is what publish-release.ps1 builds. SecretPrinter is developed and run day to day on Windows 10 22H2 (build 19045), with .NET 10: on the development machine, and on FIOS-STB-01, where it runs as a service (for one such run see the finding). From 2026-10-09 FIOS-STB-01 ran release 0.1.0, installed from the published zip in place of its build from source; by the record that is the first run of a release folder on Windows 10, and an iPhone printed through it (the finding). From 2026-10-10 a build of 5db9063 ran in its place, made on FIOS-STB-01 by publish-release.ps1, carrying .NET 10.0.12 and not signed, overnight before a release; an iPhone printed through it (the finding; the overnight run). From 2026-10-11 it ran release 0.2.0, downloaded there, checked and installed in place of that build; an iPhone printed through it (the finding). From 2026-10-14 a build of c0992a5 ran in its place, made on FIOS-STB-01 by publish-release.ps1, carrying .NET 10.0.12 and not signed; an iPhone printed through it (the finding). From later that day a build of 8663e5c ran in its place, made the same way, and Windows restarted FIOS-STB-01 twice with it running (the finding). Since 2026-10-15 it runs release 0.3.0, downloaded there, checked and installed in place of that build; it carries .NET 10.0.13, and an iPhone printed through it (the finding). On Windows 11 it has been run eight times, all on one machine, for about an hour and a quarter in all: twice on 2026-10-04, on Windows 11 Home, build 26200, from a release folder, and an iPhone printed a page each time (the finding); once on 2026-10-06, from a folder the release workflow had signed, when an iPhone printed a page again (the finding); twice more later that day, with that signed folder installed as a service, for about thirteen and seven minutes, the second time started by Windows at boot, and an iPhone printed a page in the first (the finding); twice on 2026-10-08, installed from the published pre-release by the steps of docs/operating.md, once for about three seconds, made to fail on purpose, and once for 37 minutes, when an iPhone printed a page (the finding); and once on 2026-10-10, a build of c56d697 run from a console window for 9 minutes 41 seconds, when an iPhone printed a page (the finding). It has not been run on any other version of Windows. Microsoft's list of the operating systems .NET 10 supports, as updated 2026-09-28 and read 2026-10-03, includes Windows 11 and does not include Windows 10 22H2. So the version SecretPrinter has been measured on at length is one that list leaves out, and on Windows 11 it has been measured for about an hour and a quarter, on one machine. (Updated 2026-10-03 by Claude, Claude Opus 5.5: until then this entry read "Open. No version or architecture is stated anywhere in this repository." Updated again 2026-10-04, when the first runs on Windows 11 were made: it had said SecretPrinter had been run only on Windows 10, and not as a proxy on Windows 11. Updated 2026-10-06, when a third run was made: it had said "run twice, on 2026-10-04, for about two and three minutes". Updated again 2026-10-06, when two more runs were made: it had said "run three times, for about two or three minutes each", and had ended "measured for a few minutes on one machine". Updated 2026-10-08, when two more runs were made: it had said "run five times" and "for under half an hour in all", had "and twice more later that day" where it now has "twice more later that day", and had ended "measured for under half an hour, on one machine". Updated again 2026-10-08, in the commit that sets the version to 0.1.0: "Decided 2026-09-30 and 2026-10-03" was followed by "; no release exists yet". Updated 2026-10-09, when release 0.1.0 was installed on FIOS-STB-01: the sentence beginning "Since 2026-10-09" added. Updated 2026-10-10, when a build of 5db9063 replaced 0.1.0 on FIOS-STB-01: that sentence read "Since 2026-10-09 FIOS-STB-01 runs release 0.1.0", and the sentence after it, which now begins "Since 2026-10-10", was added. The run on Windows 11 earlier that day was added at the same time: this entry had said "seven times" and "a little over an hour" in two places, and its 2026-10-08 runs began "; and twice". Updated 2026-10-11, when release 0.2.0 replaced that build on FIOS-STB-01: the sentence before the runs on Windows 11 read "Since 2026-10-10 it runs a build of 5db9063 in its place, made on FIOS-STB-01 by publish-release.ps1, carrying .NET 10.0.12 and not signed, to run overnight before a release; an iPhone printed through it", and the sentence on 0.2.0 is new. Updated 2026-10-14, when a build of c0992a5 replaced 0.2.0 on FIOS-STB-01: the sentence on 0.2.0 read "Since 2026-10-11 it runs release 0.2.0", and the sentence after it is new. Updated again later that day, when a build of 8663e5c replaced that build: the sentence on c0992a5 read "Since 2026-10-14 a build of c0992a5 runs in its place", and the sentence after it is new. Updated 2026-10-15, when release 0.3.0 replaced that build: the sentence on 8663e5c read "Since later that day a build of 8663e5c runs in its place", and the sentence after it is new.)
11 Offered both an A record and a link-local AAAA record, which address does iOS connect to, and does it connect to a link-local address it learned over mDNS at all? REQ-ADV-021 publishes both. Resolved for one iPhone, 2026-10-01: it connected to the link-local address for every connection that carried data, and printed two pages over it; its one IPv4 attempt it reset itself as an IPv6 connection opened. Other devices and iOS versions were not measured. See the finding.

15. License

MIT. See LICENSE.

The MIT license disclaims warranty. That disclaimer is legal boilerplate and does not lessen the obligations this document places on the code: the specification above describes what the software does, and if the software departs from it, that is a defect to be fixed or a specification to be corrected — not an outcome excused by the license.

Releases

Used by

Contributors

Languages