@yozz.app/tls 0.2.0 → 0.3.0

package/README.md

@@ -25,7 +25,7 @@ const result = await startTls({
   transport,
   serverName: 'imap.example.com',
   trustAnchors: compileAnchors(ROOT_BUNDLE).source,
-  validationTime: new Date(),
+  validationTime: Temporal.Now.instant(),
   validator: YOZZ_VALIDATOR,
 });
 if (result.ok) {
@@ -35,7 +35,14 @@ if (result.ok) {
 
 `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.
+connection to resume. Its `receivedAt` and `authenticatedAt` are `Temporal.Instant`s, which neither
+structured clone nor JSON keeps, so a store encodes them. Before 0.3 they were `Date`s: a store
+written by 0.2 must convert them, or `startTls` throws on the session before a byte goes out.
+
+**Requires a global `Temporal`.** Times are `Temporal.Instant`s (`validationTime`, the optional `now` clock, a session's
+instants). Node 26, Chrome and Firefox ship it; where the runtime has none (Safari, Node 24), install
+[`temporal-polyfill`](https://www.npmjs.com/package/temporal-polyfill) and load it before this package is
+imported (`import 'temporal-polyfill/global'`). The package imports no polyfill itself.
 
 `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.

package/dist/index.d.mts

@@ -107,14 +107,14 @@ type TlsSession = {
   readonly preSharedKey: Uint8Array;
   /** §4.3.11.1's `ticket_age_add`, the server's random offset. */
   readonly ticketAgeAdd: number;
-  /** A real `Date`; a persisted session must revive it. */
-  readonly receivedAt: Date;
+  /** Neither structured clone nor JSON keeps a `Temporal.Instant`: a store encodes it. */
+  readonly receivedAt: Temporal.Instant;
   readonly lifetimeSeconds: number;
   /**
    * When the peer's certificate was last verified, carried forward unchanged through every renewal:
-   * RFC 9846 §4.7.1 asks for a limit on the total lifetime of renewed keying material. A real `Date`.
+   * RFC 9846 §4.7.1 asks for a limit on the total lifetime of renewed keying material.
    */
-  readonly authenticatedAt: Date;
+  readonly authenticatedAt: Temporal.Instant;
   /** Carried forward through renewals. A name rather than a code point, so it survives the caller's store. */
   readonly peerSignatureScheme: SignatureScheme;
   /** Carried forward, so a resumed handshake can re-validate the chain against today's clock and anchors (`reverifyOnResume`). */
@@ -132,7 +132,7 @@ type StartTlsOptions = {
   readonly transport: ByteDuplex;
   readonly serverName: string;
   readonly trustAnchors: TrustAnchorSource;
-  readonly validationTime: Date;
+  readonly validationTime: Temporal.Instant;
   readonly validator: Validator;
   readonly expectedPeerName?: PeerName | null;
   /** In preference order; the first carries the key share. */
@@ -154,7 +154,7 @@ type StartTlsOptions = {
   /** Tickets arrive after the handshake, so this fires from `read()`. Without it, tickets are dropped. */
   readonly onSession?: (session: TlsSession) => void | Promise<void>;
   /** The running clock for ticket ages, distinct from `validationTime` (a policy input a caller may freeze). Injectable for BoGo. */
-  readonly now?: () => Date;
+  readonly now?: () => Temporal.Instant;
 };
 type HandshakeResult = {
   readonly ok: true;

package/dist/index.mjs

@@ -1839,6 +1839,7 @@ const isDerChain = (chain) => chain?.leafDer instanceof Uint8Array && Array.isAr
 const assertUsableSession = (session) => {
 	if (!SUPPORTED_SIGNATURE_SCHEMES.includes(session.peerSignatureScheme)) throw new Error("the stored session names no signature scheme this client implements");
 	if (!isDerChain(session.peerCertificateChain)) throw new Error("the stored session carries no usable peer certificate chain");
+	for (const field of ["receivedAt", "authenticatedAt"]) if (!(session[field] instanceof Temporal.Instant)) throw new Error(`the stored session's ${field} is not a Temporal.Instant`);
 };
 /**
 * A resumed handshake verifies no signature, so a ticket it mints inherits the original
@@ -1858,10 +1859,10 @@ const inheritedAuthentication = (resumed, verifiedNow) => {
 	return verifiedNow;
 };
 const isWithinAuthenticationCeiling = (authenticatedAt, now) => {
-	const age = now.getTime() - authenticatedAt.getTime();
+	const age = now.epochMilliseconds - authenticatedAt.epochMilliseconds;
 	return age >= 0 && age < MAX_AUTHENTICATION_AGE_SECONDS * 1e3;
 };
-const ticketAgeMs = (session, now) => now.getTime() - session.receivedAt.getTime();
+const ticketAgeMs = (session, now) => now.epochMilliseconds - session.receivedAt.epochMilliseconds;
 /** RFC 9846 §4.3.11.1: age in milliseconds plus the server's offset, modulo 2^32. */
 const obfuscatedTicketAge = (session, now) => (ticketAgeMs(session, now) + session.ticketAgeAdd) % 4294967296;
 /** `asciiLower`, not `toLowerCase`: KELVIN SIGN folds to `k` under Unicode, which would widen a security check. */
@@ -2231,7 +2232,7 @@ const clientHelloRecords = (message, legacyVersion) => Array.from({ length: Math
 /** Exported for `replay.ts` only, which `index.test.ts` enforces. */
 const runHandshake = async (options, replay) => {
 	const { transport, serverName } = options;
-	const now = options.now ?? (() => /* @__PURE__ */ new Date());
+	const now = options.now ?? (() => Temporal.Instant.fromEpochMilliseconds(Date.now()));
 	const expectedPeerName = options.expectedPeerName !== void 0 ? options.expectedPeerName : {
 		kind: "dns",
 		value: serverName

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yozz.app/tls",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A TLS 1.3 client in TypeScript over any byte duplex: record layer, handshake, key schedule, PSK resumption, KeyUpdate, TOFU pinning. Runs in Node and browsers, no native code.",
   "license": "MIT",
   "homepage": "https://github.com/fishballapp/yozz",
@@ -29,11 +29,12 @@
     "access": "public"
   },
   "dependencies": {
-    "@yozz.app/x509": "0.2.0"
+    "@yozz.app/x509": "0.3.0"
   },
   "devDependencies": {
-    "@playwright/test": "1.63.0",
+    "@playwright/test": "1.64.1",
     "@types/node": "^24.13.4",
+    "temporal-polyfill": "^1.0.8",
     "tsdown": "^0.23.0",
     "vite": "^8.3.0",
     "wrangler": "^4.131.2"