@yozz.app/tls 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fishball Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @yozz.app/tls
+
+A TLS 1.3 client (RFC 9846) in TypeScript, over any byte duplex. It is what the YOZZ mail
+client uses to reach IMAP and SMTP servers from inside a browser, where there is no socket API
+and no platform TLS to call.
+
+- Record layer, handshake state machine, key schedule, `KeyUpdate`, `close_notify`.
+- 1-RTT PSK resumption; never 0-RTT.
+- Certificate validation through [`@yozz.app/x509`](https://www.npmjs.com/package/@yozz.app/x509),
+  plus trust-on-first-use public-key pinning as a `Validator` wrapper.
+- WebCrypto only: runs in Node and in Chromium, Firefox and WebKit with no native code.
+- Gates: RFC 8448 byte-exact on all five traces; BoringSSL's BoGo runner, 296/296 in scope.
+
+```bash
+pnpm add @yozz.app/tls
+```
+
+```ts
+import { startTls } from '@yozz.app/tls';
+import { compileAnchors, ROOT_BUNDLE, YOZZ_VALIDATOR } from '@yozz.app/x509';
+
+// `transport` is a ByteDuplex: { read(): Promise<Uint8Array | null>; write(bytes): Promise<void> }
+// over whatever carries bytes to the server (a TCP socket in Node, a WebSocket relay in a browser).
+const result = await startTls({
+  transport,
+  serverName: 'imap.example.com',
+  trustAnchors: compileAnchors(ROOT_BUNDLE).source,
+  validationTime: new Date(),
+  validator: YOZZ_VALIDATOR,
+});
+if (result.ok) {
+  const { connection } = result; // read() / write() / close() over the encrypted channel
+}
+```
+
+`HandshakeResult` is a discriminated union, never a throw for a refused certificate; the refusal
+says which check failed. A session handed to `onSession` can be offered once on a later
+connection to resume.
+
+`src/index.ts` is the whole public API and says why each export exists. The source is in
+[fishballapp/yozz](https://github.com/fishballapp/yozz), which takes issues but no pull requests.
+
+MIT.

package/dist/index.d.mts

@@ -0,0 +1,511 @@
+import { PeerName, TrustAnchorSource, ValidationFailure, Validator } from "@yozz.app/x509";
+
+//#region src/wire.d.ts
+type NamedGroup = 'x25519' | 'secp256r1' | 'secp384r1';
+declare const NAMED_GROUPS: Readonly<Record<NamedGroup, number>>;
+/**
+ * Every group this client implements, in the order it offers them — so the
+ * first one carries the key share, and a server that accepts our first choice
+ * negotiates without a HelloRetryRequest.
+ *
+ * P-384 is not optional here: `posteo.de` refuses X25519 and P-256 outright.
+ *
+ * It doubles as the default for `supportedGroups`, and `wire.test.ts` holds it
+ * to covering every key of `NAMED_GROUPS` — `namedGroupFromCode` searches this
+ * list, so a group implemented but missing from it would decode as unknown.
+ */
+declare const SUPPORTED_GROUPS: readonly NamedGroup[];
+/** The wire code back to the name, `undefined` for a group we do not implement. */
+declare const namedGroupFromCode: (code: number) => NamedGroup | undefined;
+type SignatureScheme = 'ecdsa_secp256r1_sha256' | 'ecdsa_secp384r1_sha384' | 'rsa_pss_rsae_sha256' | 'rsa_pss_rsae_sha384' | 'rsa_pss_rsae_sha512' | 'ed25519';
+declare const SIGNATURE_SCHEMES: Readonly<Record<SignatureScheme, number>>;
+/**
+ * Every scheme this client can verify a CertificateVerify with, in the order it
+ * offers them, and the default for `signatureSchemes`.
+ *
+ * The list is the security boundary, not just a preference: RFC 9846 §4.5.2
+ * says a server's "signature algorithm MUST be one offered in the client's
+ * `signature_algorithms` extension", and the handshake refuses one that is not.
+ * So a scheme missing from here is a scheme the server may not sign with, and a
+ * scheme present but unimplemented in `verify.ts` is a hole — `wire.test.ts`
+ * holds this to covering every key of `SIGNATURE_SCHEMES`, the same way
+ * `SUPPORTED_GROUPS` is held to `NAMED_GROUPS`.
+ *
+ * Ed25519 is offered where BoringSSL disables it by default. It is a smaller,
+ * misuse-resistant signature over a curve we already carry for key exchange,
+ * and refusing it would only push a server onto RSA.
+ */
+declare const SUPPORTED_SIGNATURE_SCHEMES: readonly SignatureScheme[];
+/** The wire code back to the name, `undefined` for a scheme we do not implement. */
+declare const signatureSchemeFromCode: (code: number) => SignatureScheme | undefined;
+type AlertDescription = 'close_notify' | 'unexpected_message' | 'bad_record_mac' | 'record_overflow' | 'handshake_failure' | 'bad_certificate' | 'unsupported_certificate' | 'certificate_expired' | 'certificate_unknown' | 'certificate_revoked' | 'unknown_ca' | 'illegal_parameter' | 'access_denied' | 'decode_error' | 'decrypt_error' | 'protocol_version' | 'insufficient_security' | 'internal_error' | 'inappropriate_fallback' | 'user_canceled' | 'missing_extension' | 'unsupported_extension' | 'unrecognized_name' | 'bad_certificate_status_response' | 'unknown_psk_identity' | 'certificate_required' | 'general_error' | 'no_application_protocol';
+//#endregion
+//#region src/alert.d.ts
+type AlertLevel = 'warning' | 'fatal';
+type Alert = {
+  readonly level: AlertLevel;
+  readonly description: AlertDescription;
+};
+type TlsFailure = {
+  readonly kind: 'alert-sent';
+  readonly alert: Alert;
+} | {
+  readonly kind: 'alert-received';
+  readonly alert: Alert;
+}
+/**
+ * A well-formed alert whose description TLS 1.3 does not define. RFC 9846 §6:
+ * "Unknown Alert types MUST be treated as error alerts" — so the connection
+ * ends, and what the peer said is reported rather than answered. Old servers
+ * still send old alerts, and "the server sent alert 30" is a diagnosis where
+ * "we sent illegal_parameter" is not.
+ */
+| {
+  readonly kind: 'alert-received-unknown';
+  readonly code: number;
+} | {
+  readonly kind: 'truncated';
+} | {
+  readonly kind: 'certificate';
+  readonly reason: ValidationFailure;
+  readonly alert: Alert;
+  /**
+   * WHICH chain was refused, and it is the field a caller acts on.
+   *
+   * `'peer-sent'` is the chain this handshake received. `'session-stored'`
+   * is the copy a resumed session carried, re-checked because
+   * `reverifyOnResume` asked for it — and the two want opposite responses.
+   * A stored chain that no longer validates usually means the mail host has
+   * ROTATED and the session is stale, so the answer is to evict it and
+   * reconnect without one, which will very likely succeed. The same
+   * `ValidationFailure` on a peer-sent chain means the host is actually
+   * presenting something we refuse, and retrying achieves nothing but a
+   * second refusal.
+   *
+   * Two cross-model reviews landed on this independently: without it,
+   * `kind: 'certificate'` is all a caller has, `certificate-expired` reads
+   * as "this mail host's certificate expired" in both cases, and the
+   * retry-and-recover path this library tells callers to own cannot be
+   * written.
+   */
+  readonly chain: 'peer-sent' | 'session-stored';
+};
+//#endregion
+//#region src/key-schedule.d.ts
+/**
+ * TLS 1.3's key schedule — RFC 9846 §7.1 — over WebCrypto.
+ *
+ * **WebCrypto's own `HKDF` algorithm is unusable here.** It fuses extract and
+ * expand, and TLS needs the halves apart: a bare Extract for the Early,
+ * Handshake and Master secrets, and a bare Expand-Label everywhere else. Both
+ * are a few lines over `subtle.sign('HMAC')`, and every one of them is checked
+ * byte-for-byte against RFC 8448's five traces in the test beside this file.
+ *
+ * Nothing here knows what a record or a handshake message is. The transcript
+ * arrives already hashed, which is what lets the schedule be proven against the
+ * RFC before a single byte is framed.
+ */
+type CipherSuite = 'TLS_AES_128_GCM_SHA256' | 'TLS_AES_256_GCM_SHA384';
+type CipherSuiteParameters = {
+  /** The wire code point, RFC 9846 App. B.4. */readonly code: number;
+  readonly hash: 'SHA-256' | 'SHA-384';
+  readonly hashLength: number;
+  readonly keyLength: number; /** RFC 9846 §5.3: the AEAD nonce, which is 12 octets for both AES-GCM suites. */
+  readonly ivLength: number;
+};
+/**
+ * The two suites the spike measured as necessary and sufficient across real mail
+ * providers — `posteo.de` takes only the second. `TLS_CHACHA20_POLY1305_SHA256`
+ * is deliberately absent: WebCrypto has no ChaCha20, and RFC 9846 keeps it
+ * optional.
+ */
+declare const CIPHER_SUITES: Readonly<Record<CipherSuite, CipherSuiteParameters>>;
+/**
+ * RFC 5869 §2.1. An empty salt means HashLen zero octets — which is also how RFC
+ * 8446 §7.1 draws the Early Secret's `0` — and the substitution is not optional:
+ * WebCrypto refuses a zero-length HMAC key outright.
+ */
+declare const hkdfExtract: (suite: CipherSuite, salt: Uint8Array, ikm: Uint8Array) => Promise<Uint8Array>;
+/**
+ * `async` so that a rejected label fails the same way a rejected length does.
+ * Without it `hkdfLabel` throws synchronously, as an argument evaluated before
+ * the call, and a caller using `.catch()` rather than `await` would miss it.
+ */
+declare const hkdfExpandLabel: (suite: CipherSuite, secret: Uint8Array, label: string, context: Uint8Array, length: number) => Promise<Uint8Array>;
+/**
+ * RFC 9846 §7.1's `Derive-Secret(Secret, Label, Messages)` — and it takes
+ * MESSAGES, hashing them itself, because that is what the RFC's signature says.
+ *
+ * An earlier shape took the transcript pre-hashed while keeping this name. That
+ * invites a handshake author reading the RFC to pass `ClientHello ‖ ServerHello`
+ * straight in, which derives a secret that is merely different: every such bug
+ * surfaces at `Finished` as `decrypt_error`, nowhere near the cause. Pass
+ * nothing for the empty transcript. For the one derivation that takes an EMPTY
+ * context rather than `Hash("")` — the `finished` key — use `hkdfExpandLabel`.
+ */
+declare const deriveSecret: (suite: CipherSuite, secret: Uint8Array, label: string, ...messages: readonly Uint8Array[]) => Promise<Uint8Array>;
+/** `Transcript-Hash` over the handshake messages as they went on the wire. */
+declare const transcriptHash: (suite: CipherSuite, ...messages: readonly Uint8Array[]) => Promise<Uint8Array>;
+/**
+ * The three Extracts of the schedule, each folding in the one input it exists
+ * for. `Derive-Secret(., "derived", "")` between them is the step that is easy
+ * to forget, and it hashes the EMPTY transcript rather than the handshake so
+ * far.
+ */
+declare const earlySecret: (suite: CipherSuite, psk?: Uint8Array) => Promise<Uint8Array>;
+declare const handshakeSecret: (suite: CipherSuite, early: Uint8Array, sharedSecret: Uint8Array) => Promise<Uint8Array>;
+declare const masterSecret: (suite: CipherSuite, handshake: Uint8Array) => Promise<Uint8Array>;
+type TrafficKeys = {
+  readonly key: Uint8Array;
+  readonly iv: Uint8Array;
+};
+/** RFC 9846 §7.3. Both halves come off the same traffic secret. */
+declare const trafficKeys: (suite: CipherSuite, secret: Uint8Array) => Promise<TrafficKeys>;
+/** RFC 9846 §4.5.3. The base key is the sender's handshake traffic secret. */
+declare const finishedKey: (suite: CipherSuite, baseKey: Uint8Array) => Promise<Uint8Array>;
+/** Our own `Finished.verify_data`, to send. */
+declare const verifyData: (suite: CipherSuite, key: Uint8Array, transcript: Uint8Array) => Promise<Uint8Array>;
+/**
+ * Their `Finished.verify_data`, to check — through `subtle.verify`, which is
+ * constant-time, rather than a byte comparison that is not. Correctness here is
+ * free, so there is no reason to spend a timing side channel on it.
+ */
+declare const isVerifyDataValid: (suite: CipherSuite, key: Uint8Array, transcript: Uint8Array, received: Uint8Array) => Promise<boolean>;
+//#endregion
+//#region src/session.d.ts
+/**
+ * The certificates the peer actually sent, split the way
+ * `PathValidationRequest` wants them — so re-validating a stored chain is the
+ * same call over the same shape, not a reassembly that could put the leaf in
+ * the wrong slot.
+ *
+ * A leaf is not optional and the two halves are separate fields, which is what
+ * makes "the chain is empty" unrepresentable rather than a case to check.
+ */
+type PeerCertificateChain = {
+  readonly leafDer: Uint8Array;
+  readonly intermediateDer: readonly Uint8Array[];
+};
+type TlsSession = {
+  /**
+   * The host this ticket came from. A ticket is an identifier the server hands
+   * out in the clear and sees again in the clear, so offering one to a
+   * different host tells that host where else we have been.
+   */
+  readonly serverName: string;
+  /**
+   * The identity the certificate was actually checked against on the connection
+   * that issued this ticket — which is NOT always `serverName`, because
+   * `expectedPeerName` may override it and `null` disables name matching
+   * altogether.
+   *
+   * It travels with the session because a resumed handshake sends no
+   * Certificate and no CertificateVerify: there is nothing left to check the
+   * name against, so the only moment the identity can be established is the
+   * connection that issued the ticket. Without this a session minted under
+   * `null` could be offered on a connection that asked for a strict name, and
+   * the strict check would never run.
+   */
+  readonly expectedPeerName: PeerName | null;
+  /**
+   * The suite that issued it, and with it the hash the binder runs on. A
+   * server may resume at a different suite, but only one with the same hash
+   * (§4.3.11), which is why this travels with the session rather than being
+   * re-derived from whatever gets negotiated next.
+   */
+  readonly suite: CipherSuite; /** The opaque ticket, which travels as the PSK identity. */
+  readonly ticket: Uint8Array; /** §4.7.1's `PSK`, already expanded through the ticket's own nonce. */
+  readonly preSharedKey: Uint8Array; /** §4.3.11.1's `ticket_age_add`, the server's random offset. */
+  readonly ticketAgeAdd: number;
+  readonly receivedAt: Date;
+  readonly lifetimeSeconds: number;
+  /**
+   * When the peer's certificate was last actually verified — carried FORWARD
+   * unchanged through every renewal, so it dates the chain of tickets rather
+   * than the newest one.
+   *
+   * RFC 9846 §4.7.1: "it is possible to continue issuing new tickets which
+   * indefinitely extend the lifetime of the keying material originally derived
+   * from an initial non-PSK handshake (which was most likely tied to the peer's
+   * certificate). It is RECOMMENDED that implementations place limits on the
+   * total lifetime of such keying material". Without this field there is nothing
+   * to place a limit against: a resumed connection mints its own tickets, each
+   * looking brand new, and the one signature that ever proved the peer's
+   * identity recedes indefinitely into the past.
+   */
+  readonly authenticatedAt: Date;
+  /**
+   * The scheme the peer's CertificateVerify was signed with on the connection
+   * that authenticated it — carried forward through every renewal, alongside
+   * `authenticatedAt`, because they describe the same signature. The renewal
+   * step used to be asserted by no test anywhere; `session.test.ts` now drives
+   * RFC 8448 §4 through the state machine and seals a ticket under §4's own
+   * published server application key to watch all three arrive.
+   *
+   * A resumed handshake sends no CertificateVerify, so without this a caller
+   * asking "how was this peer authenticated" gets an answer on the first
+   * connection and nothing on every one after it.
+   *
+   * A NAME rather than a code point, because this is the field that goes into
+   * the caller's store: `'rsa_pss_rsae_sha512'` survives a rehydration and a
+   * table edit where `2054` reads as nothing at all.
+   */
+  readonly peerSignatureScheme: SignatureScheme;
+  /**
+   * The chain the peer sent on the connection that authenticated it — carried
+   * forward through every renewal beside `authenticatedAt` and
+   * `peerSignatureScheme`, because all three describe that one authentication.
+   *
+   * It is here so a resumed handshake can validate the peer's chain AGAIN, as
+   * of today's clock and today's trust anchors (`reverifyOnResume` in
+   * `handshake.ts`). Nothing on a resumed wire carries a certificate, so the
+   * stored copy is the only chain there is to check — and checking it is what
+   * turns an expired leaf or a root we stopped shipping into a refusal on the
+   * next reconnect rather than one up to `MAX_AUTHENTICATION_AGE_SECONDS`
+   * later.
+   *
+   * It costs the caller's store a few KB per session, which is the whole price
+   * of the check.
+   */
+  readonly peerCertificateChain: PeerCertificateChain;
+};
+//#endregion
+//#region src/transport.d.ts
+/**
+ * Duplex byte transport interface and in-memory duplex pair implementation.
+ */
+type ByteDuplex = {
+  readonly read: () => Promise<Uint8Array | null>;
+  readonly write: (bytes: Uint8Array) => Promise<void>;
+};
+//#endregion
+//#region src/handshake.d.ts
+type StartTlsOptions = {
+  readonly transport: ByteDuplex;
+  readonly serverName: string;
+  readonly trustAnchors: TrustAnchorSource;
+  readonly validationTime: Date;
+  readonly validator: Validator;
+  readonly expectedPeerName?: PeerName | null;
+  /**
+   * What `supported_groups` offers, in preference order — the first carries the
+   * key share. Defaults to every group we implement.
+   */
+  readonly supportedGroups?: readonly NamedGroup[];
+  /**
+   * What `signature_algorithms` offers, in preference order. Defaults to every
+   * scheme we implement.
+   *
+   * It is a security boundary as much as a preference: RFC 9846 §4.5.2 says a
+   * server's CertificateVerify "signature algorithm MUST be one offered in the
+   * client's `signature_algorithms` extension", and a scheme left out of this
+   * list is one the handshake below refuses with `illegal_parameter`.
+   */
+  readonly signatureSchemes?: readonly SignatureScheme[];
+  /**
+   * A session from an earlier connection to this same host, to offer for
+   * resumption. One is offered, not a list: a client that cannot tell which of
+   * its tickets a server will take is guessing, and every guess it sends is
+   * another identifier on the wire in the clear.
+   *
+   * **Offer each session once.** RFC 9846 App. C.4: "Clients SHOULD NOT reuse a
+   * ticket for multiple connections. Reuse of a ticket allows passive observers
+   * to correlate different connections." The ticket travels in the clear, so a
+   * store that keeps handing back the same one turns it into a tracking cookie.
+   * Nothing here can enforce that — the store is the caller's — so the caller
+   * evicts what it passed in and keeps whatever `onSession` hands back.
+   *
+   * A session is refused unless `serverName` and `expectedPeerName` match the
+   * connection that issued it, because a resumed handshake re-proves neither.
+   * `trustAnchors` and `validator` are NOT part of that binding: today they are
+   * the same on every connection — ARCHITECTURE.md pins one root bundle — and
+   * the day they vary per account they have to join it.
+   */
+  readonly session?: TlsSession;
+  /**
+   * Whether a resumed handshake validates the session's stored chain again,
+   * against today's clock and today's trust anchors. **Defaults to `true`.**
+   *
+   * A resumed handshake proves the peer holds the pre-shared key and nothing
+   * else: no Certificate, no CertificateVerify. So without this the certificate
+   * decision is the one made on the connection that issued the ticket, and the
+   * only thing bounding how stale it may be is
+   * `MAX_AUTHENTICATION_AGE_SECONDS` — a week. Re-validating narrows that to
+   * the reconnect: a leaf that expired an hour ago, or a root an app update
+   * stopped shipping, is refused now rather than within seven days.
+   *
+   * **It is not a substitute for that ceiling and does not retire it.** The
+   * ceiling bounds the age of the SIGNATURE, which nothing on a resumed wire
+   * re-proves; this bounds the validity of the CHAIN, which the stored copy
+   * still answers for. Two different claims, both needed.
+   *
+   * **Failure is a refused connection, not a quiet full handshake.** The
+   * session has already been accepted by the server by the time this runs, and
+   * a client that silently reconnected without it would turn "your stored chain
+   * no longer validates" into a fact nothing observes. What the caller gets
+   * instead is `{ kind: 'certificate', chain: 'session-stored' }` — and that
+   * `chain` field is the whole reason the refusal is usable: it separates a
+   * stale STORED chain, where evicting the session and reconnecting is very
+   * likely to work because the host has rotated, from a peer-sent chain we
+   * refuse, where retrying earns a second refusal. The store is the caller's,
+   * so the eviction is too.
+   *
+   * Default `true` because a check that must be asked for is a check that gets
+   * forgotten. BoringSSL's default is the other way and `-reverify-on-resume`
+   * turns it on, so the BoGo shim passes `false` explicitly.
+   */
+  readonly reverifyOnResume?: boolean;
+  /**
+   * Called once per `NewSessionTicket`, which in TLS 1.3 arrive AFTER the
+   * handshake — so this fires from `read()`, not from `startTls`. Without it no
+   * derivation runs and the tickets are dropped where they are read.
+   */
+  readonly onSession?: (session: TlsSession) => void | Promise<void>;
+  /**
+   * The client's clock, read whenever the AGE of a resumption ticket matters:
+   * once when a ticket arrives, and once per ClientHello that offers one.
+   *
+   * Deliberately not `validationTime`. That one is a POLICY input — the instant
+   * to validate a chain as of — and a caller may legitimately freeze or backdate
+   * it; a frozen clock here would report every ticket as brand new and go on
+   * offering one long past its lifetime. This is the running clock, and it is
+   * injectable because BoGo compares the reported age to `-resumption-delay` for
+   * exact equality. Defaults to the real one.
+   */
+  readonly now?: () => Date;
+};
+type HandshakeResult = {
+  readonly ok: true;
+  readonly connection: TlsConnection; /** The group the key exchange actually ran on, which a HelloRetryRequest can change. */
+  readonly negotiatedGroup: NamedGroup; /** Whether the server took the offered session, skipping its certificate. */
+  readonly isResumed: boolean; /** Whether the server asked for a second ClientHello before answering. */
+  readonly isHelloRetryRequested: boolean;
+  /**
+   * The scheme the server signed its CertificateVerify with — a NAME, like
+   * `negotiatedGroup`, because by the time it is set the handshake has
+   * already refused every code outside the offered list.
+   *
+   * A resumed handshake sends no CertificateVerify, so this is restored from
+   * the session — it names the signature that authenticated the peer, which
+   * on a resumption is the one from the connection that issued the ticket.
+   */
+  readonly peerSignatureScheme: SignatureScheme;
+  /**
+   * The pin for the key that authenticated this peer — RFC 7469's base64
+   * SHA-256 over the leaf's SubjectPublicKeyInfo — taken from the path the
+   * validator vouched for rather than re-derived from the wire.
+   *
+   * It is HERE, on a completed handshake, and nowhere else on purpose. A
+   * pin learned any earlier is a pin learned from bytes that chain to a
+   * trusted root and nothing more, which anyone on the path can send; only
+   * CertificateVerify and Finished prove the peer HOLDS the key, and both
+   * land after the last validation this connection performs. Trust on first
+   * use therefore reads this field, and a caller cannot reach it from a
+   * handshake that failed.
+   *
+   * `null` on a resumed handshake with `reverifyOnResume` off — the one
+   * configuration in which this connection validated no chain at all, so
+   * there is nothing it can honestly report. Every other path sets it,
+   * including a resumption that re-checked its stored chain, where the key
+   * that authenticated the peer is the stored leaf's.
+   */
+  readonly peerPublicKeyPin: string | null;
+} | {
+  readonly ok: false;
+  readonly reason: TlsFailure;
+};
+type TlsConnection = {
+  readonly read: () => Promise<TlsReadResult>;
+  readonly write: (plaintext: Uint8Array) => Promise<TlsWriteResult>;
+  readonly close: () => Promise<TlsCloseResult>;
+  /**
+   * RFC 9846 §7.5's exporter — key material derived from this connection for
+   * something outside it, bound to a label and a context the caller chooses.
+   *
+   * Channel binding is what YOZZ will want it for: SCRAM-SHA-256-PLUS proves
+   * to the mail server that the TLS connection carrying the SASL exchange is
+   * the same one the client believes it is on, and `tls-exporter` (RFC 9266) is
+   * the TLS 1.3 binding.
+   *
+   * **`label` may not be empty.** It becomes `HkdfLabel.label` as `"tls13 " +
+   * label`, and RFC 9846 §7.1 declares that field `opaque label<7..255>`, so
+   * six octets is not encodable. It rejects rather than deriving a key from a
+   * struct that could not go on a wire.
+   */
+  readonly exportKeyingMaterial: (label: string, context: Uint8Array, length: number) => Promise<Uint8Array>;
+};
+type TlsReadResult = {
+  readonly ok: true;
+  readonly kind: 'data';
+  readonly bytes: Uint8Array;
+} | {
+  readonly ok: true;
+  readonly kind: 'closed';
+} | {
+  readonly ok: false;
+  readonly reason: TlsFailure;
+};
+type TlsWriteResult = {
+  readonly ok: true;
+} | {
+  readonly ok: false;
+  readonly reason: TlsFailure;
+};
+type TlsCloseResult = {
+  readonly ok: true;
+} | {
+  readonly ok: false;
+  readonly reason: TlsFailure;
+};
+declare const startTls: (options: StartTlsOptions) => Promise<HandshakeResult>;
+//#endregion
+//#region src/pinning.d.ts
+/**
+ * RFC 7469 §2.1.1's pin: base64 of SHA-256 over the SubjectPublicKeyInfo DER.
+ *
+ * A STRING, and that is the load-bearing part. The pin goes into a caller's
+ * store, which for YOZZ means it is serialised and read back, and a
+ * `Uint8Array` through `JSON.stringify` becomes `{"0":48,"1":89,...}` — an
+ * object that revives as something no byte comparison will ever match, so every
+ * reconnection reads as a rotation. It is also the format `openssl x509
+ * -pubkey | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary |
+ * base64` prints, which is how a user checks a pin out of band.
+ */
+declare const publicKeyPin: (subjectPublicKeyInfoDer: Uint8Array) => Promise<string>;
+/**
+ * A `Validator` that runs another one and then refuses any chain whose leaf key
+ * is not the pinned one.
+ *
+ * The inner validator runs FIRST and its failure is returned untouched. A pin
+ * that matched could otherwise carry an expired or unanchored chain through,
+ * which would make pinning a way to weaken validation rather than a check on
+ * top of it.
+ *
+ * A mismatch is `rejected-by-policy`, which `@yozz.app/tls` maps to a
+ * `certificate_unknown` alert. It deliberately is not one of the codes that
+ * name a property of the chain: the chain is fine. Reporting a rotated key as
+ * `no-path-to-trust-anchor` would send a user to their CA over a problem that
+ * has nothing to do with one.
+ *
+ * `pin` is required. There is no null-means-allow-anything mode, because that
+ * is a pinned validator that silently never fires — a caller with no pin yet
+ * passes the unwrapped validator and learns one from the result.
+ *
+ * **One per connection**, since a pin belongs to a host and the caller is the
+ * one holding the store that maps between them. Reusing an instance across
+ * hosts refuses the second one, which is the safe direction and still a bug.
+ *
+ * ONE pin, not a set. HPKP needed a backup pin to stop a browser bricking a
+ * site it could not un-pin; a mismatch here asks the user, who can accept. The
+ * case that would need a set is a hostname behind independently keyed
+ * frontends, and every IP of all nine stage-3 mail hosts serves one key.
+ */
+declare const pinnedValidator: ({
+  validator,
+  pin
+}: {
+  readonly validator: Validator;
+  readonly pin: string;
+}) => Validator;
+//#endregion
+export { type Alert, type AlertDescription, type ByteDuplex, CIPHER_SUITES, type CipherSuite, type HandshakeResult, NAMED_GROUPS, type NamedGroup, SIGNATURE_SCHEMES, SUPPORTED_GROUPS, SUPPORTED_SIGNATURE_SCHEMES, type SignatureScheme, type StartTlsOptions, type TlsCloseResult, type TlsConnection, type TlsFailure, type TlsReadResult, type TlsSession, type TlsWriteResult, type TrafficKeys, deriveSecret, earlySecret, finishedKey, handshakeSecret, hkdfExpandLabel, hkdfExtract, isVerifyDataValid, masterSecret, namedGroupFromCode, pinnedValidator, publicKeyPin, signatureSchemeFromCode, startTls, trafficKeys, transcriptHash, verifyData };