IF Commons GitHub

Net

0001Draft

0001-net · owner if · domain commons

Downloads

FR-001checkpassing

net MUST download over fetch: classify a failure (DNS, connection, broken, timeout, TLS, certificate, an HTTP status), retry only where another try can help, waiting longer each time up to a cap or as long as the server's Retry-After asks (no longer than the cap), say and keep every retry, resume a .part file with Range, and keep a file only where its SHA-256 is the one expected.

Enforced (check): .github: cd commons/net && bun test suite/ — net.test.ts: classification, waits, Retry-After, retries against a local server, resume with Range, the SHA-256 check

Proved by: net/suite/net.test.ts

Written in: net/src/net.ts

Tests: passed: suite/net.test.ts a .part file is resumed with a Range request; passed: suite/net.test.ts a download is retried where the server is busy, not where it refuses, and kept only with t; passed: suite/net.test.ts failures are classified by code and by words, and only those another try can help are retr; passed: suite/net.test.ts the wait doubles from the base up to the cap, and the retries are said and counted

Cited by: Net, net

The server

FR-002checkpassing

serve MUST serve HTTP on node:http with a handler from a web Request to a web Response: streamed bodies both ways, every set-cookie kept, HEAD without a body, a handler that throws answered by onError (500 by default), a client that goes away aborting request.signal, 127.0.0.1 unless another address is asked for, AddrInUse where the port is taken, and a shutdown by call or by abort signal.

Enforced (check): .github: cd commons/net && bun test suite/ — net.test.ts: a real server on a free port: bodies, cookies, HEAD, a handler that throws, AddrInUse, shutdown by signal

Proved by: net/suite/net.test.ts

Written in: net/src/serve.ts

Tests: passed: suite/net.test.ts a handler of web Requests answers with web Responses: method, path, headers, cookies, stre; passed: suite/net.test.ts a port in use is AddrInUse; an aborted signal shuts the server down

Cited by: Net, serve

HTTP clients

FR-003checkpassing

http-client MUST give typed HTTP clients a transport, live over fetch or recorded (answering by method and URL, and naming a request it has no exchange for), that refuses a request carrying a credential before it is sent unless made to allow credentials; a read-only guard; backoff on 429 and 503 that waits as long as Retry-After asks, up to a cap; a JSON read decoded at the boundary whose failures are typed (refused, network, denied for 401 and 403, another status, a decode) and are said without any header or body; every item of a list paged by Link or by a cursor; and the JSON5 text a recorded exchange is kept in, read back as the same exchange.

Enforced (check): .github: cd commons/net && bun test suite/ — http-client.test.ts: against a local server: decoded reads, denials, statuses, credentials refused and allowed, read-only, backoff with Retry-After and the cap, Link and cursor paging, recorded exchanges

Proved by: net/suite/http-client.test.ts

Written in: net/src/http-client.ts

Tests: passed: suite/http-client.test.ts a JSON read is decoded, a denial and a status are told apart, and no header or body is sai; passed: suite/http-client.test.ts a credential is refused before anything is sent unless the transport allows it; read-only ; passed: suite/http-client.test.ts a recorded transport answers what was recorded and names what it has not; a recording read; passed: suite/http-client.test.ts backoff waits as long as Retry-After asks, up to the cap, else 1, 2, 4 seconds, and gives ; passed: suite/http-client.test.ts every item of a list paged by Link, and of one paged by a cursor and 1 more

Cited by: http-client, Net

FR-004checkpassing

The read-only guard of FR-003 MUST take, besides the token endpoints, a predicate over a whole POST request (method, URL, headers and body) that says it only reads (a GraphQL query, a search, a JSON API's Describe and Get actions), and MUST let through only those; PUT, PATCH and DELETE, and every other POST, MUST still be refused without being sent.

Enforced (check): .github: cd commons/net && bun test suite/ — http-client.test.ts: readOnly lets through the POSTs its predicate says only read, and refuses every other write

Proved by: net/suite/http-client.test.ts

Tests: passed: suite/http-client.test.ts read-only lets through the POSTs its predicate says only read, and refuses every other wri

FR-005checkpassing

The HTTP clients MUST be able to sign each request of a transport by crypto's AWS Signature Version 4 (withSigV4, crypto 0001-crypto FR-004), with the time read when the request is sent; a request it signed carries a credential, so the live transport MUST still refuse it unless made to allow credentials (FR-003).

Enforced (check): .github: cd commons/net && bun test suite/ — http-client.test.ts: a SigV4 transport signs each request to a recorded server, and the live transport still refuses it unless allowed

Proved by: net/suite/http-client.test.ts

Tests: passed: suite/http-client.test.ts a SigV4 transport signs each request as it is sent, and the live transport refuses it unle

TCP and DNS

FR-006checkpassing

tcp MUST listen for and make TCP connections, plain and over TLS: a listener on an address (port 0 for a free one) that gives its address and its connections as an async iterable and closes by call, abort signal or using; a connection with its local and remote addresses, a web ReadableStream and WritableStream, and close; a TLS listener from a certificate and key in PEM, and a TLS connection that checks the server's certificate against the system's roots or the ones given.

Enforced (check): .github: cd commons/net && bun test suite/ — tcp.test.ts: listen, connect, TLS with a test certificate

Proved by: net/suite/tcp.test.ts

Written in: net/src/tcp.ts, net/tools/check.ts, net/tools/pack.ts

Tests: passed: suite/tcp.test.ts a TLS listener from a PEM certificate and key: accepted with the root that signed it, refu; passed: suite/tcp.test.ts a port already taken is AddrInUse; `await using` frees it; passed: suite/tcp.test.ts a port nothing listens on refuses: ConnectionRefused, with the address; passed: suite/tcp.test.ts an abort signal closes a listener and ends its iteration; a connect aborted gives up, as T; passed: suite/tcp.test.ts an echo server on a free port: addresses, web streams both ways, half-close, then the list

Cited by: Net, tcp

FR-007checkpassing

dns MUST resolve A, AAAA, CNAME, MX, NS, TXT and SRV records, each a Result whose error says whether the name does not exist, has no such record, or could not be asked.

Enforced (check): .github: cd commons/net && bun test suite/ — dns.test.ts: resolution and its errors against a small DNS server on a free UDP port

Proved by: net/suite/dns.test.ts

Written in: net/src/dns.ts

Tests: passed: suite/dns.test.ts A, AAAA, CNAME, MX, NS, TXT and SRV records come back in their shapes; passed: suite/dns.test.ts AAAA addresses are written as RFC 5952 says (the URL standard's form): lower case, the lon; passed: suite/dns.test.ts TXT strings round-trip, whatever printable text and however many strings a record holds; passed: suite/dns.test.ts a name that does not exist, a name without the record, a server failure and an aborted que; passed: suite/dns.test.ts a query that does not come back is given up when its signal aborts: failed, not thrown and 1 more

Cited by: dns, Net, proc

ACME certificates by DNS-01

FR-008checkpassing

acme MUST give issue(o), which, given an ACME directory's URL, the names, a DnsProvider and optionally an account key, contacts, a wait for propagation and a fetch, gets a certificate: it reads the directory, gets the account (FR-010), places an order for the names, and for each authorization that is pending sets a TXT record at _acme-challenge.<name> (a wildcard's at its base name) whose value is the base64url SHA-256 of the key authorization (token.thumbprint, the thumbprint of RFC 7638); once every record is set it calls the wait for each, answers each dns-01 challenge, polls each authorization until it is valid, sends the certificate signing request of FR-013 to the order's finalize, polls the order until it is valid, and downloads the certificate as application/pem-certificate-chain. Polling MUST wait the server's Retry-After where it gives one, else a wait that grows, within a total time. The result MUST be the certificate chain as PEM, the certificate's private key as PKCS #8 PEM, the account's private key as a JWK (to keep for the next run) and the certificate's notAfter. The module MUST name Let's Encrypt's production and staging directories (LETS_ENCRYPT, LETS_ENCRYPT_STAGING).

Enforced (check): .github: cd commons/net && bun test suite/ — acme.test.ts: a name and its wildcard issued by a fake CA, the TXT values computed from its tokens and the account key

Proved by: net/suite/acme.test.ts

Written in: net/src/acme.ts

Tests: passed: suite/acme.test.ts a certificate for a name and its wildcard: TXT records of the key authorizations, answered; passed: suite/acme.test.ts the directories of Let's Encrypt are named

Cited by: ACME certificates by DNS-01

FR-009checkpassing

Every request but the directory and a new nonce MUST be a JWS in the flattened JSON serialization (application/jose+json) signed with ES256, whose protected header carries alg, the nonce and the url, and the account's public JWK until the account exists, its URL (kid) after. Each request MUST use a nonce not used before (the last Replay-Nonce, or one from newNonce), a POST-as-GET MUST send an empty payload, and a badNonce refusal MUST be sent again with the nonce it carries, up to five times.

Enforced (check): .github: cd commons/net && bun test suite/ — acme.test.ts: the fake CA verifies every JWS (ES256, nonce spent once, url, jwk only for newAccount, kid after), badNonce retried

Proved by: net/suite/acme.test.ts

Tests: passed: suite/acme.test.ts every request is an ES256 JWS the server verifies, with the JWK only to make the account a

Cited by: ACME certificates by DNS-01

FR-010checkpassing

Where no account key is given, an ES256 key MUST be made and its account made with the terms agreed and the contacts given; where a key is given, the account MUST be asked for with onlyReturnExisting and made only where the server says accountDoesNotExist. An account that is not valid, or a key that is not an ES256 private JWK, MUST be refused.

Enforced (check): .github: cd commons/net && bun test suite/ — acme.test.ts: an account made with no key, found again with the key it gave back, asked for then made for an unknown key

Proved by: net/suite/acme.test.ts

Tests: passed: suite/acme.test.ts an account key given is found again with onlyReturnExisting, or its account made when the

Cited by: ACME certificates by DNS-01

FR-011checkpassing

Every TXT record issue set MUST be removed before it returns, whether the certificate came or not. A record that cannot be removed MUST NOT lose a certificate that came: it MUST be a warning of the result, and part of the error where there is one.

Enforced (check): .github: cd commons/net && bun test suite/ — acme.test.ts: records removed after success and after an invalid authorization; a removal that fails is a warning

Proved by: net/suite/acme.test.ts

Tests: passed: suite/acme.test.ts a certificate for a name and its wildcard: TXT records of the key authorizations, answered; passed: suite/acme.test.ts a challenge the server finds invalid fails the issue, and the TXT records are still remove; passed: suite/acme.test.ts a TXT record that cannot be removed is a warning of the certificate, or added to the error

Cited by: ACME certificates by DNS-01

FR-012checkpassing

Every expected failure (the directory unreachable or not ACME's, a refusal by the server, with its problem type and detail, an authorization that is not valid, the wait running out, the DNS provider throwing, the network failing, no names) MUST be a Result with one sentence, never an exception, and no sentence MUST carry a token or a private key.

Enforced (check): .github: cd commons/net && bun test suite/ — acme.test.ts: the directory down, an invalid authorization, the DNS throwing, the network failing, the wait running out: each a Result with one sentence

Proved by: net/suite/acme.test.ts

Tests: passed: suite/acme.test.ts a challenge the server finds invalid fails the issue, and the TXT records are still remove; passed: suite/acme.test.ts the directory down, the DNS refusing, the network failing and no names are each a sentence

Cited by: ACME certificates by DNS-01

FR-013checkpassing

The certificate signing request (PKCS #10) MUST be for a new ES256 key made for the certificate, with the first name as its common name (where it is at most 64 characters) and every name as a dNSName of a subject alternative name extension requested by extensionRequest, signed with ECDSA and SHA-256 (the raw signature Web Crypto gives written as DER), and built with Formats' der.

Enforced (check): .github: cd commons/net && bun test suite/ — acme.test.ts: the CSR's signature verified with its own SPKI, its common name and SANs read back

Proved by: net/suite/acme.test.ts

Tests: passed: suite/acme.test.ts the CSR is signed by a new ES256 key, names the first name as its subject and every name a

Cited by: ACME certificates by DNS-01

FR-014checkpassing

notAfterOf(pem) MUST read the notAfter of the first certificate in PEM text (UTCTime and GeneralizedTime) with Formats' der, or give nothing where it cannot; needsRenewal(pem, now, days = 30) MUST say whether the certificate ends within days of now, or has ended, or cannot be read.

Enforced (check): .github: cd commons/net && bun test suite/ — acme.test.ts: notAfter of certificates made with der in UTCTime and GeneralizedTime, the first of a chain, needsRenewal at the edges

Proved by: net/suite/acme.test.ts

Tests: passed: suite/acme.test.ts notAfterOf reads UTCTime and GeneralizedTime; needsRenewal within the days given, or where

Cited by: ACME certificates by DNS-01

FR-015checkpassing

A DnsProvider MUST be two functions, setTxt(name, value) and removeTxt(name, value), so that any DNS host can serve. cloudflareDns({ token, zone, api? }) MUST give one over Cloudflare's API (v4, https://api.cloudflare.com/client/v4 unless another is given): the zone's id found by its name once, a TXT record added with its content quoted and a short TTL, and removed by the id it was given or, for a record made elsewhere, by its name and content; the token sent only as Authorization: Bearer; a name outside the zone, a zone the token cannot see and a refusal by the API each an error that says which, with Cloudflare's own message and never the token.

Enforced (check): .github: cd commons/net && bun test suite/ — acme.test.ts: cloudflareDns against a fake API on a local server: zone by name, a quoted TXT added and deleted, the errors

Proved by: net/suite/acme.test.ts

Tests: passed: suite/acme.test.ts cloudflareDns finds the zone by name, adds a quoted TXT record and deletes it, with the to

Cited by: ACME certificates by DNS-01

Signals and the package

FR-016checkpassing

WHEN a pipeline of Telemetry is installed, the HTTP client MUST make a client span for each request (http.request.method, url.full redacted, server.address, http.response.status_code) that sends traceparent, and serve a server span whose parent is the request's traceparent, as Telemetry requires of the runtime's own modules (commons 0001-telemetry FR-018); where none is installed they MUST make no span and send no traceparent; an OTLP receiver over serve MUST make no span of its own, so that a pipeline exporting to it does not feed itself (commons 0001-telemetry FR-019).

Enforced (check): .github: cd commons/net && bun test suite/ — otel-net.test.ts: with no pipeline the client and serve make no span and pass no traceparent; with one, the server's span is the client's child and the URL is redacted; the receiver makes no span of its own

Proved by: net/suite/otel-net.test.ts

Tests: passed: suite/otel-net.test.ts the receiver makes no span of its own, so a pipeline exporting to it does not feed itself; passed: suite/otel-net.test.ts the HTTP client's span sends traceparent, and serve's span is its child; the URL is redact; passed: suite/otel-net.test.ts with no pipeline installed, proc, the client and serve make no span and pass no traceparen

FR-017checkno test run

Net MUST depend on Core, Formats, Crypto, System and Telemetry alone, MUST name node: builtins and no vendor's global, and MUST be published as compiled modules with their declarations as @intellectual-frontiers/net (commons 0032-libraries-by-concern FR-005, FR-013), one entry for the package and one for each module, importable by Node 26 and by Bun from node_modules, with @types/node as a peer.

Enforced (check): .github: cd commons/net && bun run verify — the package is built, inspected and packed by tools/pack.ts; tests/commons-packages.test.ts installs the tarball and runs every entry on Node 26 and Bun and type-checks a consumer

Written in: net/about.ts, net/src/mod.ts

Acceptance scenarios

  1. Given a server that answers 503 with Retry-After: 120 when the cap is 30 seconds, When a download is retried, Then the wait is 30 seconds, per FR-001.
  2. Given a handler of web Requests, When serve runs it on port 0, Then the system's free port is in addr and a HEAD is answered with no body, per FR-002.
  3. Given a transport that refuses credentials, When a request carries an Authorization header, Then it is refused before it is sent and the header's value is never said, per FR-003.
  4. Given a name and its wildcard, When acme.issue runs against a fake CA, Then two TXT records are set at _acme-challenge.<name> and both are removed, per FR-008 and FR-011.
  5. Given a collector pipeline installed, When the client calls the server, Then the server's span is the child of the client's, per FR-016.
  6. Given the packed package installed under node_modules, When Node 26 and Bun import each entry, Then both give the same value, per FR-017.

Out of scope

  • HTTP-01 and TLS-ALPN-01, External Account Binding, revocation, key rollover, account deactivation and ACME Renewal Information (RFC 9773): commons may add them when a harness needs one.
  • Keys other than ES256 for the account or the certificate.
  • Where a certificate and its keys are kept, and when a harness runs issue: the harness's, with the secret store it already has.
  • Waiting for a record to be seen by the DNS: the caller's propagationWait, which can ask the zone's own servers with dns.

Edge cases

  • A request with an Authorization header to a transport that refuses credentials: refused, and the header's value never said, per FR-003.
  • A server that answers 503 with Retry-After: 120 when the cap is 30 seconds: the wait is 30 seconds, per FR-001.
  • A download whose SHA-256 is not the one expected: the .part file is removed and nothing is kept, per FR-001.
  • Port 0: the system picks a free port, and addr gives it, per FR-002.
  • A TLS connection to a server whose certificate a given root did not sign: refused, per FR-006.
  • resolveDns("nonexistent.example", "MX"): an Err saying the name does not exist, per FR-007.
  • A POST to a GraphQL endpoint holding a mutation, where the predicate lets through only query: refused, never sent, per FR-004.
  • A signed request sent by the live transport made with its default options: refused, the Authorization header named and its value never said, per FR-003 and FR-005.
  • Names example.org and *.example.org: two TXT records at _acme-challenge.example.org, each with its own value, both removed, per FR-008 and FR-011.
  • An account key given that the server does not know: asked for with onlyReturnExisting, then made, per FR-010.
  • A server that answers the first newOrder with badNonce: the order is sent again with the new nonce, and the certificate comes, per FR-009.
  • A server that always answers badNonce: an error naming badNonce after five retries, per FR-009 and FR-012.
  • A challenge whose record the CA does not find: the error says the authorization is invalid, and the record is removed, per FR-011 and FR-012.
  • The DNS provider throws on the second name: an error with its message, and the first name's record removed, per FR-011 and FR-012.
  • A certificate came, and the DNS host was down for the removal: the certificate with one warning, per FR-011.
  • An authorization that stays pending: an error when the total wait runs out, per FR-008 and FR-012.
  • A certificate that ends in 29 days: needsRenewal is true; in 31 days, false, per FR-014.
  • Text with no certificate in it: notAfterOf gives nothing, and needsRenewal is true, per FR-014.
  • setTxt("_acme-challenge.example.com", ...) on a provider for the zone example.org: an error naming both, per FR-015.

Assumptions

  • The CA follows RFC 8555 as Let's Encrypt does: Replay-Nonce on every response, Location for accounts and orders, problem documents of type urn:ietf:params:acme:error:*.
  • Web Crypto's ECDSA on P-256, its JWK, SPKI and PKCS #8 forms are in every runtime Net runs on.
  • A harness keeps the account key as a secret and gives it back to the next run; a lost key costs a new account and nothing else.
  • Tests use a fake CA, a fake Cloudflare, a small DNS server on a free UDP port and servers of their own on free local ports, and reach no real one.

Open questions

OQ-1open question

Whether to read ACME Renewal Information (RFC 9773) where the CA offers it, instead of a fixed number of days.

OQ-2open question

Which DNS host after Cloudflare a harness needs (Route 53, through Crypto's sigv4, is the likely one).

Key entities

  • Transport - what a typed HTTP client sends its requests through: live over fetch, or recorded.
  • Account key - the ES256 key that signs every request to a CA; its JWK is what a harness keeps.
  • DNS provider - where TXT records are set and removed.

Success criteria

SC-001success criterion

A harness downloads, serves, calls an API and gets a certificate with no program and no package of the network but this one.

SC-002success criterion

No TXT record of a challenge is left at the DNS host after a run.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided
  • [x] Confidential: no sensitive fact written as a literal

Cited by

dns, http-client, Net, net, serve, tcp, proc, ACME certificates by DNS-01

Titles, headings, exports, tables, columns and requirements. Esc closes.