@kagal/taistamp 0.1.1 → 0.2.0

package/README.md

@@ -69,9 +69,10 @@ absent (no echo, no signature) per [spec §5.4][spec-nonce].
 Response headers on success:
 
 | Header | Value |
-|--------|-------|
+| ------ | ----- |
 | `Content-Type` | `application/tai64n` |
 | `Content-Length` | `25` |
+| `Content-Disposition` | `inline` — browsers render the label in place rather than download it |
 | `Cache-Control` | `no-store` |
 | `TAI-Leap-Seconds` | decimal count (e.g. `37`), always present |
 
@@ -94,13 +95,19 @@ entirely.
 newTaistampHandler();                                // cors: '*' (default)
 newTaistampHandler({ cors: 'https://example.com' }); // scoped origin
 newTaistampHandler({ cors: false });                 // CORS-specific headers off
+newTaistampHandler({ corsMaxAge: 86400 });           // pre-flight cache 24h
 ```
 
+`corsMaxAge` (seconds, default `600`) sets the pre-flight
+`Access-Control-Max-Age`. The spec §5.2 floor is 600, so a
+smaller value clamps up to it; the field is ignored when
+`cors` is `false`.
+
 When CORS is enabled, responses carry:
 
 | Response | CORS headers added | `Vary: Origin` (scoped origin only) |
-|----------|--------------------|------|
-| `OPTIONS` 200 | `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods: GET, HEAD`, `Access-Control-Allow-Headers: TAI-Nonce`, `Access-Control-Expose-Headers: TAI-Leap-Seconds, TAI-Nonce, TAI-Key-Selector, TAI-Signature`, `Access-Control-Max-Age: 600` | yes |
+| -------- | ------------------ | ----------------------------------- |
+| `OPTIONS` 200 | `Access-Control-Allow-Origin`, `Access-Control-Allow-Methods: GET, HEAD`, `Access-Control-Allow-Headers: TAI-Nonce`, `Access-Control-Expose-Headers: TAI-Leap-Seconds, TAI-Nonce, TAI-Key-Selector, TAI-Signature`, `Access-Control-Max-Age` (default `600`, see `corsMaxAge`) | yes |
 | `GET` / `HEAD` 200 | `Access-Control-Allow-Origin`, `Access-Control-Expose-Headers` (so browser JS can read the `TAI-*` headers) | yes |
 | `405` | `Access-Control-Allow-Origin` | yes |
 
@@ -142,10 +149,27 @@ factory are re-exported from
 package and don't need to depend on the underlying
 package directly.
 
+Operators usually hold a `selector:base64` seed
+secret rather than a `CryptoKey`. `parseSecretToKey`
+(also re-exported) parses it into a `KeyConfig` whose
+`selector` and `signer` plug straight into the
+handler config:
+
+```typescript
+import {
+  newTaistampHandler,
+  parseSecretToKey,
+} from '@kagal/taistamp';
+
+const { selector, signer } =
+  await parseSecretToKey(env.TAISTAMP_SECRET);
+const taistamp = newTaistampHandler({ selector, signer });
+```
+
 `signer` and `selector` are co-required: pass both to
 sign, neither for an unsigned handler. Construction
 throws if only one is supplied, or if `selector` does
-not match `/^[A-Za-z](?:[\dA-Za-z_-]{0,61}[\dA-Za-z])?$/`
+not match `[A-Za-z]([A-Za-z0-9_-]{0,61}[A-Za-z0-9])?`
 (a single DNS-safe label that starts with a letter,
 ends with a letter or digit, and is also a valid
 Structured Field token).
@@ -215,7 +239,7 @@ v=tai1; k=ed25519; p=<base64-of-32-raw-pubkey-bytes>
 ```
 
 | Tag | Value |
-|-----|-------|
+| --- | ----- |
 | `v` | Protocol version. `tai1` for the framing in this README. |
 | `k` | Key algorithm. `ed25519` for the only algorithm currently defined. |
 | `p` | Public key, standard base64. For Ed25519: 32 raw bytes → 43-44 chars. |
@@ -238,22 +262,42 @@ or fall back to a strict-verify library such as
 
 ```typescript
 import {
-  asNonce,
   composeSignaturePayload,
   extractLeapSeconds,
+  extractNonce,
+  extractSignature,
+  newNonce,
+  parseRecordToVerifier,
   readLabel,
+  tai64nLabelToUTC,
 } from '@kagal/taistamp';
 
+// Mint the request nonce. `newNonce` returns a branded
+// `Nonce` — conformant sf-binary by construction — so
+// the same value flows into the signing path below.
+const nonce = newNonce();
 const response = await fetch(taistampURL, {
-  headers: { 'TAI-Nonce': clientNonce },
+  headers: { 'TAI-Nonce': nonce },
 });
 // `application/tai64n` is octet-typed, not text. `readLabel`
 // reads the raw body and decodes the 25-octet ASCII label;
 // never `response.text()`, which UTF-8-decodes and would
 // mangle a non-ASCII octet instead of surfacing it.
 const label = await readLabel(response);
-const selector = response.headers.get('TAI-Key-Selector')!;
-const sigSf = response.headers.get('TAI-Signature')!;
+const selector = response.headers.get('TAI-Key-Selector');
+if (!selector) {
+  throw new Error('TAI-Key-Selector missing');
+}
+
+// Spec §6: `TAI-Signature` carries the raw 64-octet
+// Ed25519 signature as an sf-binary item.
+// `extractSignature` returns the decoded bytes, or
+// `undefined` whenever the field is missing,
+// duplicated, malformed, or the wrong length.
+const signature = extractSignature(response.headers);
+if (signature === undefined) {
+  throw new Error('TAI-Signature missing or malformed');
+}
 
 // Spec §5.3: a `TAI-Leap-Seconds` value outside the
 // signed-payload u32 range MUST be treated as unsigned.
@@ -267,20 +311,33 @@ if (leap === undefined) {
   throw new Error('TAI-Leap-Seconds out of range; treat as unsigned');
 }
 
-// Brand the recorded nonce so it can flow into the
-// signing path. `asNonce` returns `undefined` for any
-// value that fails sf-binary syntax or the wire
-// length range — the same "treat as absent" verdict
-// the server applied per spec §5.4.
-const nonce = asNonce(clientNonce);
-if (nonce === undefined) {
-  throw new Error('client nonce is not a valid sf-binary item');
+// The response must echo `TAI-Nonce`. With no echo there
+// is no proof of freshness — the response may be a replay
+// of an earlier exchange (Plain, trust level 0, spec §8),
+// and any signature present MUST be ignored. This is
+// strictly worse than a fresh-but-unsigned response, not
+// equivalent to it.
+const echo = extractNonce(response.headers);
+if (echo === undefined) {
+  throw new Error('no TAI-Nonce echo: response is unverifiable');
+}
+// A present echo that differs from what we sent binds the
+// response to a different exchange (Inconsistent, level
+// -1) and MUST be rejected.
+if (echo !== nonce) {
+  throw new Error('TAI-Nonce echo does not match the nonce sent');
 }
 
-// Look up the public key in DNS at
-// `${selector}._taistamp.${host}` and parse the
-// `p=` tag from the TXT record.
-const publicKey = await loadPublicKey(host, selector);
+// Look up the TXT record in DNS at
+// `${selector}._taistamp.${host}`; `parseRecordToVerifier`
+// parses it and imports the published key into a
+// ready-to-use `Verifier` in `p`. A revoked record
+// (empty `p=`) carries through as `p: undefined`.
+const txtValue = await loadTXT(host, selector);
+const record = await parseRecordToVerifier(txtValue);
+if (record.p === undefined) {
+  throw new Error('key record is revoked');
+}
 
 const payload = composeSignaturePayload(
   label,
@@ -288,31 +345,46 @@ const payload = composeSignaturePayload(
   selector,
   nonce,
 );
-const valid = await crypto.subtle.verify(
-  'Ed25519',
-  publicKey,
-  sfBinaryDecode(sigSf), // strip leading/trailing ':' then base64-decode
-  payload,
-);
+const valid = await record.p.verify(signature, payload);
+if (!valid) {
+  throw new Error('signature does not verify');
+}
+
+// The signature checks out, so the label is trustworthy.
+// `tai64nLabelToUTC` decodes it to `Date.now()`-shaped
+// milliseconds — the server's signed time — honouring the
+// leap count the response declared.
+const verifiedAt = tai64nLabelToUTC(label, leap);
+if (verifiedAt === undefined) {
+  throw new Error('TAI64N label malformed');
+}
 ```
 
 `composeSignaturePayload(label, leapSeconds, selector,
 nonce)` reconstructs the exact byte sequence the
-server signed; the verifier supplies only the public
-key and an sf-binary decoder. `leapSeconds` must be a
+server signed; the verifier supplies only the DNS
+lookup — `extractSignature` hands the raw signature
+bytes straight to the `Verifier`. `leapSeconds` must be a
 branded `LeapSeconds` — obtain one from
 `extractLeapSeconds(headers)` (the verifier path) or
-`asLeapSeconds(number)` (when you already have the
+`asLeapSeconds(number | undefined)` (when you already have the
 value). Both return `undefined` for out-of-range
 input, collapsing every "treat as unsigned" case in
 [spec §5.3][spec-leap] into one verdict. `nonce` must be a branded
-`Nonce` — wrap the recorded client nonce with
+`Nonce` — `newNonce()` mints one directly; a nonce
+recorded as a plain string is branded with
 `asNonce(value)`, which returns `undefined` for any
 value that would have been treated as absent on the
 server (missing, empty, malformed sf-binary, or out
 of length range — see [spec §5.4][spec-nonce]).
-Comparing the verifier's recorded nonce against the
-response's `TAI-Nonce` defends against replay.
+`extractNonce(response.headers)` reads the echoed
+`TAI-Nonce`. With no echo the response carries no proof
+of freshness — it may be a replay of an earlier exchange,
+so any signature MUST be ignored; this is weaker than a
+fresh-but-unsigned response, not equivalent to it. A
+present echo that differs from the nonce you sent binds
+the response to a different exchange and MUST be
+rejected.
 
 ## API
 
@@ -327,12 +399,14 @@ response's `TAI-Nonce` defends against replay.
   [Signing the response](#signing-the-response) for
   signed responses, and
   [CORS](#cors) for cross-origin policy.
-- `TaistampHandlerConfig` — `{ cors?, selector?,
-  signer? }`. `cors` accepts `'*'` (default), a
-  specific origin string, or `false`; `signer` and
-  `selector` are co-required.
+- `TaistampHandlerConfig` — `{ cors?, corsMaxAge?,
+  selector?, signer? }`. `cors` accepts `'*'`
+  (default), a specific origin string, or `false`;
+  `corsMaxAge` is the pre-flight `Access-Control-Max-Age`
+  in seconds (default `600`, clamped up to a 600 floor);
+  `signer` and `selector` are co-required.
 
-### Signer
+### Signer and verifier
 
 Re-exported from `@kagal/ed25519-secret`:
 
@@ -341,6 +415,26 @@ Re-exported from `@kagal/ed25519-secret`:
 - `newEd25519Signer(key)` — WebCrypto Ed25519
   signer factory. Pass an Ed25519 private
   `CryptoKey` with `'sign'` in `usages`.
+- `parseSecretToKey(secret, context?)` — parse a
+  `selector:base64` seed secret into a `KeyConfig`;
+  its `selector` and `signer` plug straight into
+  `newTaistampHandler`.
+- `parseSecretsToKeys(secrets, strict?, context?)` —
+  the same for a string carrying several secrets
+  separated by whitespace or punctuation. Strict mode
+  (the default) rejects the whole call on a malformed
+  entry; lenient mode skips it.
+- `KeyConfig` — parsed secret: the `selector`,
+  ready-to-use `signer` / `verifier`, and the
+  underlying key material.
+- `parseRecordToVerifier(record, context?)` — parse a
+  DNS TXT key record into a `KeyRecord` whose `p` is
+  a ready-to-use `Verifier`, or `undefined` for a
+  revoked record (empty `p=`).
+- `KeyRecord` — parsed TXT record: the tag-value
+  pairs with `p` upgraded to the parse target.
+- `Verifier` — `{ verify: (signature, message) =>
+  Promise<boolean> }`.
 
 ### Verification helpers
 
@@ -360,9 +454,9 @@ For verifier-side validation of a signed response
 - `composeSignaturePayload(label, leapSeconds,
   selector, nonce)` — reconstructs the exact byte
   sequence the server signed.
-- `asLeapSeconds(number)` — brand a numeric
-  leap-second count; returns `undefined` for
-  out-of-range input.
+- `asLeapSeconds(number | undefined)` — brand a numeric
+  leap-second count; returns `undefined` for an absent
+  or out-of-range input.
 - `extractLeapSeconds(headers)` — parse
   `TAI-Leap-Seconds` from response headers; returns
   `undefined` if missing, non-numeric, non-integer,
@@ -373,42 +467,107 @@ For verifier-side validation of a signed response
   returns `undefined` for any value that fails
   sf-binary syntax or the length range checked
   per [spec §5.4][spec-nonce].
+- `extractNonce(headers)` — read and brand the
+  `TAI-Nonce` echo from a response (or the request,
+  server-side); returns `undefined` when the field is
+  missing or fails `asNonce`. On the verifying side
+  `undefined` means no proof of freshness — the response
+  may be a replay and any signature MUST be ignored,
+  weaker than a fresh-but-unsigned response; a present
+  echo must match the nonce you sent.
+- `newNonce(byteLength?, context?)` — mint a fresh
+  client nonce: random bytes framed as an sf-binary
+  item, returned already branded — conformant by
+  construction, no `asNonce` round-trip. `byteLength`
+  defaults to 16; throws `TypeError` outside
+  [spec §5.4][spec-nonce]'s 7..129 decoded octets.
 - `Nonce` — branded sf-binary nonce accepted by
   `composeSignaturePayload`.
+- `asSignature(value)` — decode a recorded
+  `TAI-Signature` value ([spec §6][spec-sign]) to the
+  raw 64-octet Ed25519 signature; returns `undefined`
+  for any value that fails sf-binary syntax or does
+  not decode to exactly 64 octets.
+- `extractSignature(headers)` — read `TAI-Signature`
+  from response headers; returns `undefined` if the
+  field is missing or fails `asSignature` validation.
+- `tai64nLabelFromUTC(utc)` — the TAI64N label for a
+  UTC millisecond timestamp. Labels are fixed-width
+  hex and order lexicographically, so a received
+  label can be freshness-checked between the labels
+  of `Date.now() - skew` and `Date.now() + skew`
+  without decoding it.
+- `tai64nLabelToUTC(label, leapSeconds?)` — the
+  inverse: recover the `Date.now()`-shaped UTC
+  milliseconds behind a verified label, so a checked
+  response yields a usable time. Returns `undefined`
+  for a malformed label; `leapSeconds` defaults to the
+  current `TAI_LEAP_SECONDS`.
+
+### sf-binary helpers
+
+`TAI-Nonce` and `TAI-Signature` travel as sf-binary
+items ([RFC 9651 §3.3.5][sf-binary]) — standard base64
+wrapped in colons. The `@kagal/taistamp/utils` subpath
+exposes the framing helpers the handler uses:
+
+```typescript
+import { decodeSFBinary } from '@kagal/taistamp/utils';
+```
+
+| Export | Description |
+| ------ | ----------- |
+| `SF_BINARY_PATTERN` | `RegExp` matching the full sf-binary syntax |
+| `encodeSFBinary(bytes)` | Bytes → `:base64:` item |
+| `decodeSFBinary(value, context?)` | `:base64:` item → bytes; throws `TypeError` on invalid syntax; `context` prefixes the message |
+
+`decodeSFBinary` enforces the full syntax — anything
+`SF_BINARY_PATTERN` rejects throws — so decoding a
+wire value needs no separate validation step; the
+pattern stands alone for validating without decoding.
 
 ### TAI64N helpers
 
-The handler uses these primitives internally; they
-are re-exported for callers that need raw TAI64N
-construction:
+Constructing TAI64N timestamps and their labels is
+a core capability of the package — the
+`@kagal/taistamp/utils` subpath exposes it for
+direct use, and the handler builds on the same
+primitives:
+
+```typescript
+import { tai64nLabel } from '@kagal/taistamp/utils';
+```
 
 | Export | Description |
-|--------|-------------|
+| ------ | ----------- |
 | `now()` | Current TAI as `{ sec, nano, offset }` |
 | `fromUTC(utc)` | `Date.now()`-shaped milliseconds → TAI timestamp |
 | `tai64nLabel(t?)` | 25-byte label string for a timestamp (or `now()`) |
-| `tai64nLabelFromUTC(utc)` | Shortcut for `tai64nLabel(fromUTC(utc))` |
+| `tai64nLabelFromUTC(utc)` | Shortcut for `tai64nLabel(fromUTC(utc))`; also on the main export |
+| `tai64nLabelToUTC(label, leapSeconds?)` | Inverse of `tai64nLabelFromUTC` — label → `Date.now()`-shaped ms, or `undefined` if malformed; also on the main export |
+| `TAI64N_LABEL_PATTERN` | `RegExp` matching the TAI64N label wire form (`@` + 24 hex digits) |
+| `TAI64N_LABEL_LENGTH` | `25` — byte length of a TAI64N label |
+| `TAI64N_CONTENT_TYPE` | `application/tai64n` — media type of a label body |
+| `TAI64N_EPOCH_HI` | `0x40000000` — TAI64 epoch high word folded into a label's seconds field |
 
 `fromUTC` applies the constant `TAI_LEAP_SECONDS`
-(currently 37 seconds). Historic UTC timestamps
-spanning a leap-second boundary need caller-side
-adjustment — the constant tracks the present, not
-history.
+(currently 37 seconds). These helpers deal in the
+current time: the offset tracks the present, and
+anything before the unix epoch is out of scope.
 
 ### Constants
 
 | Name | Value |
-|------|-------|
+| ---- | ----- |
 | `TAISTAMP_PATH` | `/.well-known/taistamp` |
-| `TAI64N_CONTENT_TYPE` | `application/tai64n` |
-| `TAI64N_CONTENT_LENGTH` | `25` |
-| `TAI64N_HEADER_KEY_SELECTOR` | `TAI-Key-Selector` |
-| `TAI64N_HEADER_LEAP_SECONDS` | `TAI-Leap-Seconds` |
-| `TAI64N_HEADER_NONCE` | `TAI-Nonce` |
-| `TAI64N_HEADER_SIGNATURE` | `TAI-Signature` |
+| `TAISTAMP_CONTENT_TYPE` | `application/tai64n` |
+| `TAISTAMP_CONTENT_LENGTH` | `25` |
+| `TAISTAMP_HEADER_KEY_SELECTOR` | `TAI-Key-Selector` |
+| `TAISTAMP_HEADER_LEAP_SECONDS` | `TAI-Leap-Seconds` |
+| `TAISTAMP_HEADER_NONCE` | `TAI-Nonce` |
+| `TAISTAMP_HEADER_SIGNATURE` | `TAI-Signature` |
 | `TAI_LEAP_SECONDS` | `37` (current TAI − UTC offset) |
 | `TAI_LEAP_SECONDS_MAX` | `0xFFFFFFFF` (signed-payload u32 cap) |
-| `TAI64_EPOCH_HI` | `0x40000000` |
 
 ## Licence
 
@@ -423,7 +582,9 @@ history.
 [npm-badge]: https://img.shields.io/npm/v/@kagal/taistamp.svg
 [npm-url]: https://www.npmjs.com/package/@kagal/taistamp
 [rfc-repo]: https://github.com/karasz/rfc-taistamp
+[sf-binary]: https://datatracker.ietf.org/doc/html/rfc9651#section-3.3.5
 [spec-leap]: https://datatracker.ietf.org/doc/html/draft-mery-nagy-taistamp-00#section-5.3
 [spec-nonce]: https://datatracker.ietf.org/doc/html/draft-mery-nagy-taistamp-00#section-5.4
+[spec-sign]: https://datatracker.ietf.org/doc/html/draft-mery-nagy-taistamp-00#section-6
 [spec-verify]: https://datatracker.ietf.org/doc/html/draft-mery-nagy-taistamp-00#section-9
 [tai64n]: https://cr.yp.to/libtai/tai64.html

package/dist/_chunks/time.d.mts

@@ -0,0 +1,144 @@
+/** `@` followed by 24 hex digits — the TAI64N label wire form. */
+declare const TAI64N_LABEL_PATTERN: RegExp;
+/** Byte length of a TAI64N label: `@` + 16 sec + 8 nano hex digits. */
+declare const TAI64N_LABEL_LENGTH: number;
+/** Media type of a TAI64N label body. */
+declare const TAI64N_CONTENT_TYPE = "application/tai64n";
+/** High 32 bits of the TAI64 second count at the unix epoch. */
+declare const TAI64N_EPOCH_HI = 1073741824;
+/** @deprecated Renamed to {@link TAI64N_EPOCH_HI}. */
+declare const TAI64_EPOCH_HI = 1073741824;
+declare const TAISTAMP_PATH = "/.well-known/taistamp";
+/** The taistamp response `Content-Type`. */
+declare const TAISTAMP_CONTENT_TYPE = "application/tai64n";
+/** The taistamp response `Content-Length`. */
+declare const TAISTAMP_CONTENT_LENGTH: number;
+declare const TAISTAMP_HEADER_KEY_SELECTOR = "TAI-Key-Selector";
+declare const TAISTAMP_HEADER_LEAP_SECONDS = "TAI-Leap-Seconds";
+declare const TAISTAMP_HEADER_NONCE = "TAI-Nonce";
+declare const TAISTAMP_HEADER_SIGNATURE = "TAI-Signature";
+/** @deprecated Renamed to {@link TAISTAMP_PATH}. */
+declare const TAI64N_PATH = "/.well-known/taistamp";
+/** @deprecated Renamed to {@link TAISTAMP_CONTENT_LENGTH}. */
+declare const TAI64N_CONTENT_LENGTH: number;
+/** @deprecated Renamed to {@link TAISTAMP_HEADER_KEY_SELECTOR}. */
+declare const TAI64N_HEADER_KEY_SELECTOR = "TAI-Key-Selector";
+/** @deprecated Renamed to {@link TAISTAMP_HEADER_LEAP_SECONDS}. */
+declare const TAI64N_HEADER_LEAP_SECONDS = "TAI-Leap-Seconds";
+/** @deprecated Renamed to {@link TAISTAMP_HEADER_NONCE}. */
+declare const TAI64N_HEADER_NONCE = "TAI-Nonce";
+/** @deprecated Renamed to {@link TAISTAMP_HEADER_SIGNATURE}. */
+declare const TAI64N_HEADER_SIGNATURE = "TAI-Signature";
+/**
+ * Upper bound for `leapSeconds` in the taistamp signed
+ * payload. The framing encodes the value as a 4-byte
+ * big-endian unsigned integer, so any input outside
+ * `[0, 2^32-1]` cannot be represented. Verifiers MUST
+ * treat an out-of-range `TAI-Leap-Seconds` response
+ * header as unsigned, per spec §5.3.
+ */
+declare const TAI_LEAP_SECONDS_MAX = 4294967295;
+declare const LeapSecondsBrand: unique symbol;
+/**
+ * `number` that has been confirmed to fit the
+ * `[0, TAI_LEAP_SECONDS_MAX]` u32be range required by
+ * the taistamp signed-payload framing. Construct only
+ * via {@link extractLeapSeconds} or {@link asLeapSeconds};
+ * the brand prevents an arbitrary number from reaching
+ * the signing path.
+ */
+type LeapSeconds = number & {
+  readonly [LeapSecondsBrand]: never;
+};
+/**
+ * Coerce a `number` to a {@link LeapSeconds}. Returns
+ * `undefined` when `value` is absent, non-integer,
+ * negative, or exceeds {@link TAI_LEAP_SECONDS_MAX}.
+ */
+declare const asLeapSeconds: (value: number | undefined) => LeapSeconds | undefined;
+/**
+ * Current TAI − UTC offset in whole seconds, used by
+ * `fromUTC()` and emitted in the `TAI-Leap-Seconds`
+ * response header. The value 37 has been in force
+ * since 2017-01-01; update on the next IERS leap-second
+ * announcement.
+ *
+ * @remarks
+ * Stays a single `LeapSeconds` until a leap-seconds
+ * table is added so the offset can be computed for any
+ * TAI second; this constant becomes redundant then.
+ */
+declare const TAI_LEAP_SECONDS: LeapSeconds;
+/**
+ * Extract a usable leap-seconds count from response
+ * headers. Returns `undefined` when the
+ * `TAI-Leap-Seconds` field is missing, empty,
+ * non-numeric, non-integer, negative, or out-of-range
+ * — every "treat as unsigned" case in spec §5.3
+ * collapsed into one verdict.
+ */
+declare const extractLeapSeconds: (headers: Headers) => LeapSeconds | undefined;
+type timestamp = {
+  nano: number;
+  sec: number;
+  offset?: number;
+};
+/**
+ * Convert a UTC timestamp in milliseconds (the
+ * `Date.now()` shape) to TAI seconds and nanoseconds,
+ * applying the current `TAI_LEAP_SECONDS` offset. The
+ * package deals in the current time: the offset tracks
+ * the present, and anything before the unix epoch is
+ * out of scope.
+ */
+declare const fromUTC: (utc: number) => timestamp;
+/**
+ * The current TAI time as seconds and nanoseconds —
+ * {@link fromUTC} applied to `Date.now()`.
+ */
+declare const now: () => timestamp;
+/**
+ * Format a TAI timestamp as the 25-byte TAI64N label
+ * served at `/.well-known/taistamp`: `@` followed by
+ * 16 hex digits of TAI64 seconds (the 2^62 epoch
+ * offset applied) and 8 hex digits of nanoseconds.
+ * Defaults to {@link now} when no value is given.
+ */
+declare const tai64nLabel: (value?: timestamp) => string;
+/**
+ * The 25-byte TAI64N label for a UTC timestamp in
+ * milliseconds — shorthand for
+ * `tai64nLabel(fromUTC(utc))`.
+ *
+ * Labels are fixed-width hex, so they order
+ * lexicographically: a verifier can bounds-check a
+ * received label between the labels of
+ * `Date.now() - skew` and `Date.now() + skew` without
+ * decoding it.
+ */
+declare const tai64nLabelFromUTC: (utc: number) => string;
+/**
+ * Recover a UTC timestamp in milliseconds (the
+ * `Date.now()` shape) from a TAI64N label — the inverse
+ * of {@link tai64nLabelFromUTC}. A label minted from a
+ * millisecond value round-trips back to it exactly; a
+ * `Date` is one `new Date(ms)` away.
+ *
+ * Returns `undefined` for any value that is not `@`
+ * followed by 24 hex digits (either case) — the
+ * verify-side "malformed is absent" collapse shared with
+ * `asSignature` and `asNonce`, so it drops straight into
+ * a gate pipeline.
+ *
+ * `leapSeconds` is the TAI − UTC offset removed when
+ * mapping TAI back to UTC; it defaults to the current
+ * {@link TAI_LEAP_SECONDS}, mirroring {@link fromUTC}.
+ * Pass a response's `extractLeapSeconds(headers)` to
+ * honour a server that declared a different count — an
+ * absent or malformed header yields `undefined` there
+ * and falls through to the default, while a genuine `0`
+ * is honoured.
+ */
+declare const tai64nLabelToUTC: (label: string, leapSeconds?: LeapSeconds) => number | undefined;
+export { LeapSeconds, TAI64N_CONTENT_LENGTH, TAI64N_CONTENT_TYPE, TAI64N_EPOCH_HI, TAI64N_HEADER_KEY_SELECTOR, TAI64N_HEADER_LEAP_SECONDS, TAI64N_HEADER_NONCE, TAI64N_HEADER_SIGNATURE, TAI64N_LABEL_LENGTH, TAI64N_LABEL_PATTERN, TAI64N_PATH, TAI64_EPOCH_HI, TAISTAMP_CONTENT_LENGTH, TAISTAMP_CONTENT_TYPE, TAISTAMP_HEADER_KEY_SELECTOR, TAISTAMP_HEADER_LEAP_SECONDS, TAISTAMP_HEADER_NONCE, TAISTAMP_HEADER_SIGNATURE, TAISTAMP_PATH, TAI_LEAP_SECONDS, TAI_LEAP_SECONDS_MAX, asLeapSeconds, extractLeapSeconds, fromUTC, now, tai64nLabel, tai64nLabelFromUTC, tai64nLabelToUTC };
+//# sourceMappingURL=time.d.mts.map

package/dist/_chunks/time.mjs

@@ -0,0 +1,68 @@
+import { decodeBase64, encodeBase64, isInRange } from "@kagal/ed25519-secret";
+const TAI64N_LABEL_PATTERN = /^@[\da-fA-F]{24}$/;
+const TAI64N_LABEL_LENGTH = 25;
+const TAI64N_CONTENT_TYPE = "application/tai64n";
+const TAI64N_EPOCH_HI = 1073741824;
+const TAI64_EPOCH_HI = TAI64N_EPOCH_HI;
+const TAISTAMP_PATH = "/.well-known/taistamp";
+const TAISTAMP_CONTENT_TYPE = TAI64N_CONTENT_TYPE;
+const TAISTAMP_CONTENT_LENGTH = 25;
+const TAISTAMP_HEADER_KEY_SELECTOR = "TAI-Key-Selector";
+const TAISTAMP_HEADER_LEAP_SECONDS = "TAI-Leap-Seconds";
+const TAISTAMP_HEADER_NONCE = "TAI-Nonce";
+const TAISTAMP_HEADER_SIGNATURE = "TAI-Signature";
+const TAI64N_PATH = TAISTAMP_PATH;
+const TAI64N_CONTENT_LENGTH = 25;
+const TAI64N_HEADER_KEY_SELECTOR = TAISTAMP_HEADER_KEY_SELECTOR;
+const TAI64N_HEADER_LEAP_SECONDS = TAISTAMP_HEADER_LEAP_SECONDS;
+const TAI64N_HEADER_NONCE = TAISTAMP_HEADER_NONCE;
+const TAI64N_HEADER_SIGNATURE = TAISTAMP_HEADER_SIGNATURE;
+const TAI_LEAP_SECONDS_MAX = 4294967295;
+const asLeapSeconds = (value) => {
+	if (!isInRange(value, 0, 4294967295)) return void 0;
+	return value;
+};
+const TAI_LEAP_SECONDS = 37;
+const DECIMAL_INTEGER = /^(?:0|[1-9]\d*)$/;
+const extractLeapSeconds = (headers) => {
+	const raw = headers.get(TAISTAMP_HEADER_LEAP_SECONDS);
+	if (!raw || !DECIMAL_INTEGER.test(raw)) return void 0;
+	return asLeapSeconds(Number(raw));
+};
+const SF_BINARY_PATTERN = /^:(?:(?:[\d+/A-Za-z]{4})*(?:[\d+/A-Za-z]{4}|[\d+/A-Za-z]{3}=|[\d+/A-Za-z]{2}==))?:$/;
+const encodeSFBinary = (bytes) => `:${encodeBase64(bytes)}:`;
+const decodeSFBinary = (value, context) => {
+	if (!SF_BINARY_PATTERN.test(value)) {
+		const prefix = context ? `${context}: ` : "";
+		throw new TypeError(`${prefix}invalid sf-binary`);
+	}
+	return decodeBase64(value.slice(1, -1), context);
+};
+const fromUTC = (utc) => {
+	return {
+		sec: Math.floor(utc / 1e3) + 37,
+		nano: utc % 1e3 * 1e6,
+		offset: 37
+	};
+};
+const now = () => {
+	return fromUTC(Date.now());
+};
+const tai64nLabel = (value) => {
+	const { sec, nano } = value ?? now();
+	const secHi = Math.trunc(sec / u32Range) + TAI64N_EPOCH_HI;
+	const secLo = sec % u32Range;
+	return `@${secHi.toString(16).padStart(8, "0")}${secLo.toString(16).padStart(8, "0")}${nano.toString(16).padStart(8, "0")}`;
+};
+const tai64nLabelFromUTC = (utc) => tai64nLabel(fromUTC(utc));
+const tai64nLabelToUTC = (label, leapSeconds = 37) => {
+	if (!TAI64N_LABEL_PATTERN.test(label)) return void 0;
+	const secHi = Number.parseInt(label.slice(1, 9), 16) - TAI64N_EPOCH_HI;
+	const secLo = Number.parseInt(label.slice(9, 17), 16);
+	const nano = Number.parseInt(label.slice(17, 25), 16);
+	return (secHi * u32Range + secLo - leapSeconds) * 1e3 + nano / 1e6;
+};
+const u32Range = 4294967296;
+export { SF_BINARY_PATTERN, TAI64N_CONTENT_LENGTH, TAI64N_CONTENT_TYPE, TAI64N_EPOCH_HI, TAI64N_HEADER_KEY_SELECTOR, TAI64N_HEADER_LEAP_SECONDS, TAI64N_HEADER_NONCE, TAI64N_HEADER_SIGNATURE, TAI64N_LABEL_LENGTH, TAI64N_LABEL_PATTERN, TAI64N_PATH, TAI64_EPOCH_HI, TAISTAMP_CONTENT_LENGTH, TAISTAMP_CONTENT_TYPE, TAISTAMP_HEADER_KEY_SELECTOR, TAISTAMP_HEADER_LEAP_SECONDS, TAISTAMP_HEADER_NONCE, TAISTAMP_HEADER_SIGNATURE, TAISTAMP_PATH, TAI_LEAP_SECONDS, TAI_LEAP_SECONDS_MAX, asLeapSeconds, decodeSFBinary, encodeSFBinary, extractLeapSeconds, fromUTC, now, tai64nLabel, tai64nLabelFromUTC, tai64nLabelToUTC };
+
+//# sourceMappingURL=time.mjs.map

package/dist/_chunks/time.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.mjs","names":[],"sources":["../../src/const.ts","../../src/leap-seconds.ts","../../src/sf-binary.ts","../../src/time.ts"],"sourcesContent":["//\n// tai64n format\n//\n// Constants describing the TAI64N label itself, surfaced on\n// the `@kagal/taistamp/utils` subpath.\n//\n\n/** `@` followed by 24 hex digits — the TAI64N label wire form. */\nexport const TAI64N_LABEL_PATTERN = /^@[\\da-fA-F]{24}$/;\n\n/** Byte length of a TAI64N label: `@` + 16 sec + 8 nano hex digits. */\nexport const TAI64N_LABEL_LENGTH = 1 + 16 + 8;\n\n/** Media type of a TAI64N label body. */\nexport const TAI64N_CONTENT_TYPE = 'application/tai64n';\n\n/** High 32 bits of the TAI64 second count at the unix epoch. */\nexport const TAI64N_EPOCH_HI = 0x40_00_00_00;\n\n/** @deprecated Renamed to {@link TAI64N_EPOCH_HI}. */\nexport const TAI64_EPOCH_HI = TAI64N_EPOCH_HI;\n\n//\n// taistamp protocol\n//\n// Constants describing the taistamp HTTP exchange, surfaced\n// on the main entry point.\n//\n\nexport const TAISTAMP_PATH = '/.well-known/taistamp';\n\n/** The taistamp response `Content-Type`. */\nexport const TAISTAMP_CONTENT_TYPE = TAI64N_CONTENT_TYPE;\n\n/** The taistamp response `Content-Length`. */\nexport const TAISTAMP_CONTENT_LENGTH = TAI64N_LABEL_LENGTH;\n\nexport const TAISTAMP_HEADER_KEY_SELECTOR = 'TAI-Key-Selector';\nexport const TAISTAMP_HEADER_LEAP_SECONDS = 'TAI-Leap-Seconds';\nexport const TAISTAMP_HEADER_NONCE = 'TAI-Nonce';\nexport const TAISTAMP_HEADER_SIGNATURE = 'TAI-Signature';\n\n//\n// Back-compat aliases for the released TAI64N_-prefixed\n// protocol names, surfaced on the /utils subpath.\n//\n\n/** @deprecated Renamed to {@link TAISTAMP_PATH}. */\nexport const TAI64N_PATH = TAISTAMP_PATH;\n\n/** @deprecated Renamed to {@link TAISTAMP_CONTENT_LENGTH}. */\nexport const TAI64N_CONTENT_LENGTH = TAISTAMP_CONTENT_LENGTH;\n\n/** @deprecated Renamed to {@link TAISTAMP_HEADER_KEY_SELECTOR}. */\nexport const TAI64N_HEADER_KEY_SELECTOR = TAISTAMP_HEADER_KEY_SELECTOR;\n\n/** @deprecated Renamed to {@link TAISTAMP_HEADER_LEAP_SECONDS}. */\nexport const TAI64N_HEADER_LEAP_SECONDS = TAISTAMP_HEADER_LEAP_SECONDS;\n\n/** @deprecated Renamed to {@link TAISTAMP_HEADER_NONCE}. */\nexport const TAI64N_HEADER_NONCE = TAISTAMP_HEADER_NONCE;\n\n/** @deprecated Renamed to {@link TAISTAMP_HEADER_SIGNATURE}. */\nexport const TAI64N_HEADER_SIGNATURE = TAISTAMP_HEADER_SIGNATURE;\n","// cspell:words IERS\n\nimport { isInRange } from '@kagal/ed25519-secret';\n\nimport { TAISTAMP_HEADER_LEAP_SECONDS } from './const';\n\n/**\n * Upper bound for `leapSeconds` in the taistamp signed\n * payload. The framing encodes the value as a 4-byte\n * big-endian unsigned integer, so any input outside\n * `[0, 2^32-1]` cannot be represented. Verifiers MUST\n * treat an out-of-range `TAI-Leap-Seconds` response\n * header as unsigned, per spec §5.3.\n */\nexport const TAI_LEAP_SECONDS_MAX = 0xFF_FF_FF_FF;\n\ndeclare const LeapSecondsBrand: unique symbol;\n\n/**\n * `number` that has been confirmed to fit the\n * `[0, TAI_LEAP_SECONDS_MAX]` u32be range required by\n * the taistamp signed-payload framing. Construct only\n * via {@link extractLeapSeconds} or {@link asLeapSeconds};\n * the brand prevents an arbitrary number from reaching\n * the signing path.\n */\nexport type LeapSeconds = number & { readonly [LeapSecondsBrand]: never };\n\n/**\n * Coerce a `number` to a {@link LeapSeconds}. Returns\n * `undefined` when `value` is absent, non-integer,\n * negative, or exceeds {@link TAI_LEAP_SECONDS_MAX}.\n */\nexport const asLeapSeconds = (\n  value: number | undefined,\n): LeapSeconds | undefined => {\n  if (!isInRange(value, 0, TAI_LEAP_SECONDS_MAX)) return undefined;\n  return value as LeapSeconds;\n};\n\n/**\n * Current TAI − UTC offset in whole seconds, used by\n * `fromUTC()` and emitted in the `TAI-Leap-Seconds`\n * response header. The value 37 has been in force\n * since 2017-01-01; update on the next IERS leap-second\n * announcement.\n *\n * @remarks\n * Stays a single `LeapSeconds` until a leap-seconds\n * table is added so the offset can be computed for any\n * TAI second; this constant becomes redundant then.\n */\nexport const TAI_LEAP_SECONDS: LeapSeconds = 37 as LeapSeconds;\n\n/**\n * Strict decimal integer: a single `0` or a non-zero\n * leading digit followed by digits. Rejects hex\n * (`0x25`), float-style integers (`37.0`), signs,\n * whitespace, exponential notation, and leading zeros\n * — every input `Number()` would silently coerce to\n * an integer despite not being a canonical decimal.\n */\nconst DECIMAL_INTEGER = /^(?:0|[1-9]\\d*)$/;\n\n/**\n * Extract a usable leap-seconds count from response\n * headers. Returns `undefined` when the\n * `TAI-Leap-Seconds` field is missing, empty,\n * non-numeric, non-integer, negative, or out-of-range\n * — every \"treat as unsigned\" case in spec §5.3\n * collapsed into one verdict.\n */\nexport const extractLeapSeconds = (\n  headers: Headers,\n): LeapSeconds | undefined => {\n  const raw = headers.get(TAISTAMP_HEADER_LEAP_SECONDS);\n  if (!raw || !DECIMAL_INTEGER.test(raw)) return undefined;\n  return asLeapSeconds(Number(raw));\n};\n","import { type Bytes, decodeBase64, encodeBase64 } from '@kagal/ed25519-secret';\n\n/**\n * sf-binary item per RFC 9651 §3.3.5: standard base64\n * with `=` padding, wrapped in a leading and trailing\n * colon. The empty payload (`::`) is valid sf-binary;\n * consumers impose their own length bounds. The\n * alphabet contains no `,`, so a duplicated field\n * (joined by the Web `Headers` API with `,`) fails the\n * same check.\n */\nexport const SF_BINARY_PATTERN =\n  /^:(?:(?:[\\d+/A-Za-z]{4})*(?:[\\d+/A-Za-z]{4}|[\\d+/A-Za-z]{3}=|[\\d+/A-Za-z]{2}==))?:$/;\n\n/**\n * Encode bytes as an sf-binary item (RFC 9651 §3.3.5):\n * standard base64 wrapped in colons. The output\n * satisfies {@link SF_BINARY_PATTERN} and round-trips\n * through {@link decodeSFBinary}.\n */\nexport const encodeSFBinary = (bytes: Readonly<Uint8Array>): string =>\n  `:${encodeBase64(bytes)}:`;\n\n/**\n * Decode an sf-binary item back into bytes. Enforces\n * the full RFC 9651 §3.3.5 syntax: throws `TypeError`\n * when `value` does not satisfy\n * {@link SF_BINARY_PATTERN}; the thrown message is\n * optionally prefixed `<context>: `.\n */\nexport const decodeSFBinary = (\n  value: string,\n  context?: string,\n): Bytes => {\n  if (!SF_BINARY_PATTERN.test(value)) {\n    const prefix = context ? `${context}: ` : '';\n    throw new TypeError(`${prefix}invalid sf-binary`);\n  }\n  // the pattern guarantees decodable standard base64\n  return decodeBase64(value.slice(1, -1), context);\n};\n","import { TAI64N_EPOCH_HI, TAI64N_LABEL_PATTERN } from './const';\nimport { type LeapSeconds, TAI_LEAP_SECONDS } from './leap-seconds';\n\ntype timestamp = {\n  nano: number\n  sec: number\n\n  offset?: number\n};\n\n/**\n * Convert a UTC timestamp in milliseconds (the\n * `Date.now()` shape) to TAI seconds and nanoseconds,\n * applying the current `TAI_LEAP_SECONDS` offset. The\n * package deals in the current time: the offset tracks\n * the present, and anything before the unix epoch is\n * out of scope.\n */\nexport const fromUTC = (utc: number): timestamp => {\n  // TODO: leap seconds table\n  const sec = Math.floor(utc / 1000) + TAI_LEAP_SECONDS;\n  const nano = (utc % 1000) * 1e6;\n  return { sec, nano, offset: TAI_LEAP_SECONDS };\n};\n\n/**\n * The current TAI time as seconds and nanoseconds —\n * {@link fromUTC} applied to `Date.now()`.\n */\nexport const now = (): timestamp => {\n  const utc = Date.now();\n  return fromUTC(utc);\n};\n\n/**\n * Format a TAI timestamp as the 25-byte TAI64N label\n * served at `/.well-known/taistamp`: `@` followed by\n * 16 hex digits of TAI64 seconds (the 2^62 epoch\n * offset applied) and 8 hex digits of nanoseconds.\n * Defaults to {@link now} when no value is given.\n */\nexport const tai64nLabel = (value?: timestamp): string => {\n  const { sec, nano } = value ?? now();\n\n  const secHi = Math.trunc(sec / u32Range) + TAI64N_EPOCH_HI;\n  const secLo = sec % u32Range;\n\n  const secHiHex = secHi.toString(16).padStart(8, '0');\n  const secLoHex = secLo.toString(16).padStart(8, '0');\n  const nanoHex = nano.toString(16).padStart(8, '0');\n\n  return `@${secHiHex}${secLoHex}${nanoHex}`;\n};\n\n/**\n * The 25-byte TAI64N label for a UTC timestamp in\n * milliseconds — shorthand for\n * `tai64nLabel(fromUTC(utc))`.\n *\n * Labels are fixed-width hex, so they order\n * lexicographically: a verifier can bounds-check a\n * received label between the labels of\n * `Date.now() - skew` and `Date.now() + skew` without\n * decoding it.\n */\nexport const tai64nLabelFromUTC = (utc: number): string =>\n  tai64nLabel(fromUTC(utc));\n\n/**\n * Recover a UTC timestamp in milliseconds (the\n * `Date.now()` shape) from a TAI64N label — the inverse\n * of {@link tai64nLabelFromUTC}. A label minted from a\n * millisecond value round-trips back to it exactly; a\n * `Date` is one `new Date(ms)` away.\n *\n * Returns `undefined` for any value that is not `@`\n * followed by 24 hex digits (either case) — the\n * verify-side \"malformed is absent\" collapse shared with\n * `asSignature` and `asNonce`, so it drops straight into\n * a gate pipeline.\n *\n * `leapSeconds` is the TAI − UTC offset removed when\n * mapping TAI back to UTC; it defaults to the current\n * {@link TAI_LEAP_SECONDS}, mirroring {@link fromUTC}.\n * Pass a response's `extractLeapSeconds(headers)` to\n * honour a server that declared a different count — an\n * absent or malformed header yields `undefined` there\n * and falls through to the default, while a genuine `0`\n * is honoured.\n */\nexport const tai64nLabelToUTC = (\n  label: string,\n  leapSeconds: LeapSeconds = TAI_LEAP_SECONDS,\n): number | undefined => {\n  if (!TAI64N_LABEL_PATTERN.test(label)) return undefined;\n\n  // The 64-bit seconds field must be read as two 32-bit\n  // words: parsing all 16 hex digits at once yields\n  // 2^62 + sec ≈ 4.6e18, whose float64 ULP (1024) has\n  // already discarded sec's low bits before the epoch\n  // base could be subtracted. Removing TAI64N_EPOCH_HI on\n  // the high word alone keeps every term exact.\n  const secHi = Number.parseInt(label.slice(1, 9), 16) - TAI64N_EPOCH_HI;\n  const secLo = Number.parseInt(label.slice(9, 17), 16);\n  const nano = Number.parseInt(label.slice(17, 25), 16);\n\n  const sec = secHi * u32Range + secLo;\n  return (sec - leapSeconds) * 1000 + nano / 1e6;\n};\n\nconst u32Range = 0x1_00_00_00_00;\n"],"mappings":";AAQA,MAAa,uBAAuB;AAGpC,MAAa,sBAAsB;AAGnC,MAAa,sBAAsB;AAGnC,MAAa,kBAAkB;AAG/B,MAAa,iBAAiB;AAS9B,MAAa,gBAAgB;AAG7B,MAAa,wBAAwB;AAGrC,MAAa,0BAAA;AAEb,MAAa,+BAA+B;AAC5C,MAAa,+BAA+B;AAC5C,MAAa,wBAAwB;AACrC,MAAa,4BAA4B;AAQzC,MAAa,cAAc;AAG3B,MAAa,wBAAA;AAGb,MAAa,6BAA6B;AAG1C,MAAa,6BAA6B;AAG1C,MAAa,sBAAsB;AAGnC,MAAa,0BAA0B;;;;;;ACjDvC,MAAa,mBAAA;;;;CAmBb,IAAA,CAAa,OAAA,CAAA,gBACX,KAC4B,GAAA,GAAA,OAAA,KAAA;CAC5B,OAAK,cAAU,OAAO,GAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;CAoCxB,OAAa,IAAA,MAAA,SAAA,EACX,EAAA,SAC4B,GAAA,GAAA,IAAA,MAAA,SAAA,EAAA,EAAA,SAAA,GAAA,GAAA,IAAA,KAAA,SAAA,EAAA,EAAA,SAAA,GAAA,GAAA;;MAG5B,sBAAqB,QAAW,YAAA,QAAA,GAAA,CAAA"}