@kagal/taistamp 0.0.5 → 0.1.0

package/README.md

@@ -1,4 +1,8 @@
-# @kagal/taistamp
+# @kagal/taistamp — HTTP handler for Ed25519-signed TAI64N timestamps
+
+[![jsDocs.io][jsdocs-badge]][jsdocs-url]
+[![npm version][npm-badge]][npm-url]
+[![Licence: MIT][mit-badge]][mit]
 
 Platform-neutral handler for `/.well-known/taistamp` —
 serves signed [TAI64N][tai64n] timestamps over HTTP for
@@ -6,13 +10,32 @@ clients that need authenticated wall-clock time without
 running an NTP stack or trusting an unauthenticated TLS
 handshake clock.
 
+Runs anywhere with `crypto.subtle` — modern browsers,
+Node ≥ 20, Cloudflare Workers, Deno, and Bun.
+
+## Specification
+
+Implements [`draft-mery-nagy-taistamp`][draft], the
+IETF Internet-Draft for signed TAI64N timestamps over
+HTTP. Working version: [`karasz/rfc-taistamp`][rfc-repo].
+Inline `spec §N` citations in this README resolve
+against that document.
+
 ## Install
 
+```sh
+npm install @kagal/taistamp
+```
+
+```sh
+yarn add @kagal/taistamp
+```
+
 ```sh
 pnpm add @kagal/taistamp
 ```
 
-## Handler
+## Usage
 
 ```typescript
 import { newTaistampHandler, TAISTAMP_PATH } from '@kagal/taistamp';
@@ -41,7 +64,7 @@ with `Allow: GET, HEAD, OPTIONS`; other methods return
 `405` with the same `Allow`. A `TAI-Nonce` that is
 missing, empty, duplicated, not a valid sf-binary
 value, or outside the 14–174 octet range is treated as
-absent (no echo, no signature) per spec §5.2.
+absent (no echo, no signature) per [spec §5.4][spec-nonce].
 
 Response headers on success:
 
@@ -98,7 +121,7 @@ answered with `200` and
 (RFC 9110 §9.3.7) is independent of cross-origin
 policy.
 
-## Signing
+## Signing the response
 
 ```typescript
 import {
@@ -122,12 +145,13 @@ package directly.
 `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][A-Za-z0-9_-]{0,62}` (a single
-DNS-safe label that starts with a letter and is also a
-valid Structured Field token).
+not match `/^[A-Za-z](?:[\dA-Za-z_-]{0,61}[\dA-Za-z])?$/`
+(a single DNS-safe label that starts with a letter,
+ends with a letter or digit, and is also a valid
+Structured Field token).
 
 When the request is a `GET` carrying a valid
-`TAI-Nonce` (see Handler section for the
+`TAI-Nonce` (see Usage section for the
 "treat as absent" rules) *and* a signer is configured,
 the response gains:
 
@@ -157,8 +181,11 @@ The framed payload is:
   length-prefixed by a single byte, so a downgrade
   attacker cannot rewrite `TAI-Key-Selector` without
   invalidating the signature.
-- `nonceBytes` — the request nonce, verbatim
-  (including any sf-binary `:` framing).
+- `nonceBytes` — the octet sequence obtained by
+  decoding the `TAI-Nonce` field value as an
+  sf-binary item per RFC 9651. The textual
+  `:base64:` framing is not part of the signed
+  input (spec §6.1).
 
 `newEd25519Signer(key: CryptoKey)` is the built-in
 signer — pass an Ed25519 private `CryptoKey` with
@@ -199,10 +226,10 @@ then removing the old TXT once cached responses have
 expired. Verifiers cache by selector, so old
 signatures stay verifiable until their TXT is removed.
 
-## Verifying
+## Verifying a signature
 
-Spec §7 requires verifiers to use the RFC 8032
-§5.1.7 strict verification procedure (cofactor
+[Spec §9][spec-verify] requires verifiers to use the
+RFC 8032 §5.1.7 strict verification procedure (cofactor
 handling, signature-malleability resistance).
 WebCrypto's `Ed25519 verify` is specified to apply
 strict verification; confirm your runtime conforms,
@@ -223,7 +250,7 @@ const label = await response.text();
 const selector = response.headers.get('TAI-Key-Selector')!;
 const sigSf = response.headers.get('TAI-Signature')!;
 
-// Spec §5.1: a `TAI-Leap-Seconds` value outside the
+// Spec §5.3: a `TAI-Leap-Seconds` value outside the
 // signed-payload u32 range MUST be treated as unsigned.
 // `extractLeapSeconds` returns `undefined` whenever
 // the field is missing, empty, non-numeric, non-integer,
@@ -237,9 +264,9 @@ if (leap === undefined) {
 
 // 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 14..174
-// octet range — the same "treat as absent" verdict
-// the server applied.
+// 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');
@@ -273,16 +300,68 @@ branded `LeapSeconds` — obtain one from
 `asLeapSeconds(number)` (when you already have the
 value). Both return `undefined` for out-of-range
 input, collapsing every "treat as unsigned" case in
-spec §5.1 into one verdict. `nonce` must be a branded
+[spec §5.3][spec-leap] into one verdict. `nonce` must be a branded
 `Nonce` — wrap the recorded client nonce 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
-outside 14..174 octets). Comparing the verifier's
-recorded nonce against the response's `TAI-Nonce`
-defends against replay.
-
-## TAI64N helpers
+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.
+
+## API
+
+- `VERSION` — package version string, mirrors
+  `package.json#version`.
+
+### Handler
+
+- `newTaistampHandler(config?)` — async fetch
+  handler for `/.well-known/taistamp`. See
+  [Usage](#usage) above for behaviour,
+  [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.
+
+### Signer
+
+Re-exported from `@kagal/ed25519-secret`:
+
+- `Signer` — `{ sign: (message: BufferSource) =>
+  Promise<ArrayBuffer> }`.
+- `newEd25519Signer(key)` — WebCrypto Ed25519
+  signer factory. Pass an Ed25519 private
+  `CryptoKey` with `'sign'` in `usages`.
+
+### Verification helpers
+
+For verifier-side validation of a signed response
+(see [Verifying a signature](#verifying-a-signature)):
+
+- `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.
+- `extractLeapSeconds(headers)` — parse
+  `TAI-Leap-Seconds` from response headers; returns
+  `undefined` if missing, non-numeric, non-integer,
+  negative, or out of range.
+- `LeapSeconds` — branded leap-second count
+  accepted by `composeSignaturePayload`.
+- `asNonce(value)` — brand a recorded nonce;
+  returns `undefined` for any value that fails
+  sf-binary syntax or the length range checked
+  per [spec §5.4][spec-nonce].
+- `Nonce` — branded sf-binary nonce accepted by
+  `composeSignaturePayload`.
+
+### TAI64N helpers
 
 The handler uses these primitives internally; they
 are re-exported for callers that need raw TAI64N
@@ -301,7 +380,7 @@ spanning a leap-second boundary need caller-side
 adjustment — the constant tracks the present, not
 history.
 
-## Constants
+### Constants
 
 | Name | Value |
 |------|-------|
@@ -321,5 +400,15 @@ history.
 [MIT][mit]
 
 <!-- references -->
+[draft]: https://datatracker.ietf.org/doc/draft-mery-nagy-taistamp/
+[jsdocs-badge]: https://img.shields.io/badge/jsDocs.io-reference-blue
+[jsdocs-url]: https://www.jsdocs.io/package/@kagal/taistamp
 [mit]: ../../LICENCE.txt
+[mit-badge]: https://img.shields.io/badge/Licence-MIT-blue.svg
+[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
+[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-verify]: https://datatracker.ietf.org/doc/html/draft-mery-nagy-taistamp-00#section-9
 [tai64n]: https://cr.yp.to/libtai/tai64.html

package/dist/index.d.mts

@@ -15,7 +15,7 @@ declare const TAI64_EPOCH_HI = 1073741824;
  * 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.1.
+ * header as unsigned, per spec §5.3.
  */
 declare const TAI_LEAP_SECONDS_MAX = 4294967295;
 declare const LeapSecondsBrand: unique symbol;
@@ -54,19 +54,21 @@ declare const TAI_LEAP_SECONDS: LeapSeconds;
  * 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.1
+ * — every "treat as unsigned" case in spec §5.3
  * collapsed into one verdict.
  */
 declare const extractLeapSeconds: (headers: Headers) => LeapSeconds | undefined;
 declare const NonceBrand: unique symbol;
 /**
  * `string` that has been confirmed to satisfy the
- * sf-binary syntax of RFC 9651 §3.3.5 and the
- * `[NONCE_MIN_OCTETS, NONCE_MAX_OCTETS]` length range
- * required by spec §5.2. Construct only via
- * {@link asNonce} or {@link extractNonce}; the brand
- * prevents arbitrary strings from reaching the
- * signing path.
+ * sf-binary syntax of RFC 9651 §3.3.5 and to fall
+ * inside the wire-form length range
+ * `[NONCE_MIN_OCTETS, NONCE_MAX_OCTETS]` — the
+ * pre-decode form of spec §5.4's normative
+ * decoded-length bound of 7..129 octets. Construct
+ * only via {@link asNonce} or {@link extractNonce};
+ * the brand prevents arbitrary strings from reaching
+ * the signing path.
  */
 type Nonce = string & {
   readonly [NonceBrand]: never;
@@ -74,9 +76,11 @@ type Nonce = string & {
 /**
  * Brand `value` as a {@link Nonce} when it satisfies
  * sf-binary syntax (RFC 9651 §3.3.5) and falls inside
- * `[NONCE_MIN_OCTETS, NONCE_MAX_OCTETS]`. Returns
+ * `[NONCE_MIN_OCTETS, NONCE_MAX_OCTETS]` — the wire
+ * range equivalent to spec §5.4's normative
+ * decoded-length bound of 7..129 octets. Returns
  * `undefined` for anything else — every "treat as
- * absent" case in spec §5.2 collapsed into one
+ * absent" case in spec §5.4 collapsed into one
  * verdict.
  */
 declare const asNonce: (value: string) => Nonce | undefined;
@@ -101,7 +105,9 @@ declare const asNonce: (value: string) => Nonce | undefined;
  *   trailing NUL byte), then the label bytes, then
  *   the leap-seconds count as a 4-byte big-endian
  *   unsigned integer, then a 1-byte selector length,
- *   then the selector bytes, then the nonce bytes.
+ *   then the selector bytes, then the decoded sf-binary
+ *   octets of the nonce (spec §6.1 — the wire
+ *   `:base64:` framing is not signed).
  *
  * @remarks
  * Binding the selector into the signed payload stops a
@@ -155,7 +161,7 @@ interface TaistampHandlerConfig {
    * gains `Access-Control-Allow-Origin`; pre-flight
    * `OPTIONS` also carries `-Allow-Methods`,
    * `-Allow-Headers`, `-Expose-Headers`, and
-   * `-Max-Age: 600` per spec §4.2; success
+   * `-Max-Age: 600` per spec §5.2; success
    * `GET` / `HEAD` carry `-Expose-Headers` so browser
    * JS can read the `TAI-*` response headers. A
    * non-`'*'` value adds `Vary: Origin` so caches can
@@ -197,11 +203,11 @@ interface TaistampHandlerConfig {
  *   `Allow: GET, HEAD, OPTIONS`.
  * - Request `TAI-Nonce` — on `GET`, the value is echoed
  *   verbatim in the response. A missing, empty,
- *   duplicated, structurally malformed, or out-of-range
- *   (14..174 octets) field is treated as absent (no
- *   echo, no signature) per spec §5.2 — see
+ *   duplicated, structurally malformed, or
+ *   length-out-of-range field is treated as absent (no
+ *   echo, no signature) per spec §5.4 — see
  *   {@link extractNonce}. `HEAD`, `OPTIONS`, and `405`
- *   responses never carry `TAI-Nonce` per spec §4.1.
+ *   responses never carry `TAI-Nonce` per spec §5.1.
  * - Request `TAI-Nonce` *and* `signer` configured *and*
  *   the request method is `GET` — adds
  *   `TAI-Key-Selector` and `TAI-Signature` (sf-binary)

package/dist/index.d.ts

@@ -0,0 +1,244 @@
+import { Signer, Signer as Signer$1, newSigner as newEd25519Signer } from "@kagal/ed25519-secret";
+declare const TAISTAMP_PATH = "/.well-known/taistamp";
+/** @deprecated Renamed to {@link TAISTAMP_PATH}. */
+declare const TAI64N_PATH = "/.well-known/taistamp";
+declare const TAI64N_CONTENT_TYPE = "application/tai64n";
+declare const TAI64N_CONTENT_LENGTH: number;
+declare const TAI64N_HEADER_KEY_SELECTOR = "TAI-Key-Selector";
+declare const TAI64N_HEADER_LEAP_SECONDS = "TAI-Leap-Seconds";
+declare const TAI64N_HEADER_NONCE = "TAI-Nonce";
+declare const TAI64N_HEADER_SIGNATURE = "TAI-Signature";
+declare const TAI64_EPOCH_HI = 1073741824;
+/**
+ * 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 non-integer, negative,
+ * or exceeds {@link TAI_LEAP_SECONDS_MAX}.
+ */
+declare const asLeapSeconds: (value: number) => 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;
+declare const NonceBrand: unique symbol;
+/**
+ * `string` that has been confirmed to satisfy the
+ * sf-binary syntax of RFC 9651 §3.3.5 and to fall
+ * inside the wire-form length range
+ * `[NONCE_MIN_OCTETS, NONCE_MAX_OCTETS]` — the
+ * pre-decode form of spec §5.4's normative
+ * decoded-length bound of 7..129 octets. Construct
+ * only via {@link asNonce} or {@link extractNonce};
+ * the brand prevents arbitrary strings from reaching
+ * the signing path.
+ */
+type Nonce = string & {
+  readonly [NonceBrand]: never;
+};
+/**
+ * Brand `value` as a {@link Nonce} when it satisfies
+ * sf-binary syntax (RFC 9651 §3.3.5) and falls inside
+ * `[NONCE_MIN_OCTETS, NONCE_MAX_OCTETS]` — the wire
+ * range equivalent to spec §5.4's normative
+ * decoded-length bound of 7..129 octets. Returns
+ * `undefined` for anything else — every "treat as
+ * absent" case in spec §5.4 collapsed into one
+ * verdict.
+ */
+declare const asNonce: (value: string) => Nonce | undefined;
+/**
+ * Compose the byte sequence covered by a TAI-Signature.
+ *
+ * @param label - the 25-byte TAI64N label string the
+ *   server is returning
+ * @param leapSeconds - the leap-seconds count the server
+ *   advertises in `TAI-Leap-Seconds`
+ * @param selector - the key selector the server
+ *   advertises in `TAI-Key-Selector`; verifiers use
+ *   this to look up the public key in DNS at
+ *   `<selector>._taistamp.<host>`
+ * @param nonce - the client-supplied nonce, echoed
+ *   verbatim in `TAI-Nonce`; brand a verifier-side
+ *   string with {@link asNonce} before passing it in
+ * @returns the byte sequence verifiers reconstruct
+ *   from the response and pass to their public-key
+ *   verify routine. The framing is the
+ *   domain-separation tag (`taistamp-v1` plus a
+ *   trailing NUL byte), then the label bytes, then
+ *   the leap-seconds count as a 4-byte big-endian
+ *   unsigned integer, then a 1-byte selector length,
+ *   then the selector bytes, then the decoded sf-binary
+ *   octets of the nonce (spec §6.1 — the wire
+ *   `:base64:` framing is not signed).
+ *
+ * @remarks
+ * Binding the selector into the signed payload stops a
+ * downgrade attacker from rewriting `TAI-Key-Selector`
+ * to point at a compromised or weaker key — the
+ * signature would no longer verify under that key.
+ * `leapSeconds` is encoded as a 4-byte big-endian
+ * unsigned integer; the selector is length-prefixed by
+ * a single byte (selectors are ≤ 63 chars per
+ * {@link newTaistampHandler}'s validation).
+ */
+declare const composeSignaturePayload: (label: string, leapSeconds: LeapSeconds, selector: string, nonce: Nonce) => ArrayBuffer;
+/**
+ * Configuration for {@link newTaistampHandler}.
+ *
+ * @remarks
+ * `signer` and `selector` are co-required: pass both
+ * to enable authenticated responses, or neither for
+ * an unsigned handler. Passing only one is rejected
+ * at construction time — without the selector
+ * verifiers cannot find the key in DNS, and a
+ * selector without a signer is a misconfiguration.
+ */
+interface TaistampHandlerConfig {
+  /**
+   * Key selector advertised in the `TAI-Key-Selector`
+   * response header and bound into the signed payload.
+   * Verifiers look up the public key at
+   * `<selector>._taistamp.<host>` in DNS.
+   *
+   * Must match `[A-Za-z][A-Za-z0-9_-]{0,62}` (a single
+   * DNS label starting with a letter, using
+   * DKIM-compatible characters and a valid sf-token);
+   * rotate by changing the selector and publishing a
+   * new TXT record.
+   */
+  selector?: string;
+  /**
+   * {@link Signer} that produces `TAI-Signature` over
+   * the framed payload from {@link composeSignaturePayload}.
+   * Without a signer the nonce is still echoed but the
+   * response is unsigned.
+   */
+  signer?: Signer$1;
+  /**
+   * CORS origin policy. Defaults to `'*'`; pass `false`
+   * to disable CORS entirely, or a specific origin
+   * (e.g. `'https://example.com'`) to scope the policy.
+   *
+   * Every response (`GET` / `HEAD` / `OPTIONS` / `405`)
+   * gains `Access-Control-Allow-Origin`; pre-flight
+   * `OPTIONS` also carries `-Allow-Methods`,
+   * `-Allow-Headers`, `-Expose-Headers`, and
+   * `-Max-Age: 600` per spec §5.2; success
+   * `GET` / `HEAD` carry `-Expose-Headers` so browser
+   * JS can read the `TAI-*` response headers. A
+   * non-`'*'` value adds `Vary: Origin` so caches can
+   * keep per-origin variants distinct.
+   *
+   * Disabling CORS does not affect method discovery:
+   * `OPTIONS` is still answered with `200` and
+   * `Allow: GET, HEAD, OPTIONS` per RFC 9110 §9.3.7.
+   */
+  cors?: false | string;
+}
+/**
+ * Build a handler for `/.well-known/taistamp`.
+ *
+ * @param config - optional {@link TaistampHandlerConfig}
+ * @returns an `async (request) => Response` callable
+ *   directly as a Web `fetch` handler or as a Hono
+ *   route handler.
+ *
+ * @throws TypeError if `signer` and `selector` are not
+ *   both set or both unset, or if `selector` does not
+ *   match `[A-Za-z][A-Za-z0-9_-]{0,62}`.
+ *
+ * @remarks
+ * Behaviour:
+ *
+ * - `GET` / `HEAD` — body is a fresh 25-byte TAI64N
+ *   label (`HEAD` omits the body). Response headers:
+ *   Content-Type `application/tai64n`, Content-Length
+ *   `25`, Cache-Control `no-store`, plus
+ *   `TAI-Leap-Seconds` carrying the current count.
+ * - `OPTIONS` — `200` with `Allow: GET, HEAD, OPTIONS`.
+ *   When CORS is enabled (the default) the response
+ *   also carries `Access-Control-Allow-*` and
+ *   `-Expose-Headers` per
+ *   {@link TaistampHandlerConfig.cors}. `OPTIONS` is
+ *   never signed.
+ * - Any other method — `405 Method Not Allowed` with
+ *   `Allow: GET, HEAD, OPTIONS`.
+ * - Request `TAI-Nonce` — on `GET`, the value is echoed
+ *   verbatim in the response. A missing, empty,
+ *   duplicated, structurally malformed, or
+ *   length-out-of-range field is treated as absent (no
+ *   echo, no signature) per spec §5.4 — see
+ *   {@link extractNonce}. `HEAD`, `OPTIONS`, and `405`
+ *   responses never carry `TAI-Nonce` per spec §5.1.
+ * - Request `TAI-Nonce` *and* `signer` configured *and*
+ *   the request method is `GET` — adds
+ *   `TAI-Key-Selector` and `TAI-Signature` (sf-binary)
+ *   over the bytes produced by
+ *   {@link composeSignaturePayload}. The
+ *   domain-separation tag means the same key cannot
+ *   be tricked into producing valid signatures for
+ *   other protocols. `HEAD`, `OPTIONS`, and `405`
+ *   responses are never signed.
+ *
+ * The corresponding public key is expected to be
+ * published out-of-band as a DNS TXT record at
+ * `<selector>._taistamp.<host>` — verifiers fetch the
+ * key by selector so the operator can rotate keys by
+ * publishing a new selector while the old one is
+ * still cached.
+ *
+ * @see {@link https://cr.yp.to/libtai/tai64.html} for
+ *   TAI64N format
+ */
+declare const newTaistampHandler: (config?: TaistampHandlerConfig) => ((request: Request) => Promise<Response>);
+type timestamp = {
+  nano: number;
+  sec: number;
+  offset?: number;
+};
+declare const fromUTC: (utc: number) => timestamp;
+declare const now: () => timestamp;
+declare const tai64nLabel: (value?: timestamp) => string;
+declare const tai64nLabelFromUTC: (utc: number) => string;
+/** Package version from package.json. */
+declare const VERSION: string;
+export { type LeapSeconds, type Nonce, type Signer, TAI64N_CONTENT_LENGTH, TAI64N_CONTENT_TYPE, TAI64N_HEADER_KEY_SELECTOR, TAI64N_HEADER_LEAP_SECONDS, TAI64N_HEADER_NONCE, TAI64N_HEADER_SIGNATURE, TAI64N_PATH, TAI64_EPOCH_HI, TAISTAMP_PATH, TAI_LEAP_SECONDS, TAI_LEAP_SECONDS_MAX, type TaistampHandlerConfig, VERSION, asLeapSeconds, asNonce, composeSignaturePayload, extractLeapSeconds, fromUTC, newEd25519Signer, newTaistampHandler, now, tai64nLabel, tai64nLabelFromUTC };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { assertValidSelector, newSigner as newEd25519Signer } from "@kagal/ed25519-secret";
-var version = "0.0.5";
+import { assertValidSelector, decodeBase64, encodeBase64, newSigner as newEd25519Signer } from "@kagal/ed25519-secret";
+var version = "0.1.0";
 const TAISTAMP_PATH = "/.well-known/taistamp";
 const TAI64N_PATH = TAISTAMP_PATH;
 const TAI64N_CONTENT_TYPE = "application/tai64n";
@@ -88,19 +88,10 @@ const u32Range = 4294967296;
 const ALLOW_HEADER = "GET, HEAD, OPTIONS";
 const textEncoder = new TextEncoder();
 const DOMAIN_SEPARATOR = textEncoder.encode("taistamp-v1\0");
-const asBytes = (source) => {
-	if (source instanceof Uint8Array) return source;
-	if (ArrayBuffer.isView(source)) return new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
-	return new Uint8Array(source);
-};
-const encodeStructuredBinary = (source) => {
-	const bytes = asBytes(source);
-	return `:${btoa(String.fromCodePoint(...bytes))}:`;
-};
 const composeSignaturePayload = (label, leapSeconds, selector, nonce) => {
 	const labelBytes = textEncoder.encode(label);
 	const selectorBytes = textEncoder.encode(selector);
-	const nonceBytes = textEncoder.encode(nonce);
+	const nonceBytes = decodeBase64(nonce.slice(1, -1));
 	const buffer = new ArrayBuffer(DOMAIN_SEPARATOR.length + labelBytes.length + 4 + 1 + selectorBytes.length + nonceBytes.length);
 	const view = new Uint8Array(buffer);
 	let offset = 0;
@@ -132,7 +123,7 @@ const fromHandlerConfig = (config) => {
 			const payload = composeSignaturePayload(label, 37, selector, nonce);
 			const signature = await signer.sign(payload);
 			headers.set(TAI64N_HEADER_KEY_SELECTOR, selector);
-			headers.set(TAI64N_HEADER_SIGNATURE, encodeStructuredBinary(signature));
+			headers.set(TAI64N_HEADER_SIGNATURE, `:${encodeBase64(new Uint8Array(signature))}:`);
 		} : void 0,
 		corsHeaders
 	};

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["pkg.version"],"sources":["../package.json","../src/const.ts","../src/cors.ts","../src/leap-seconds.ts","../src/nonce.ts","../src/utils.ts","../src/handler.ts","../src/index.ts"],"sourcesContent":["","export const TAISTAMP_PATH = '/.well-known/taistamp';\n\n/** @deprecated Renamed to {@link TAISTAMP_PATH}. */\nexport const TAI64N_PATH = TAISTAMP_PATH;\n\nexport const TAI64N_CONTENT_TYPE = 'application/tai64n';\nexport const TAI64N_CONTENT_LENGTH = 1 + 16 + 8; // '@' + sec (16 hex chars) + nano (8 hex chars)\n\nexport const TAI64N_HEADER_KEY_SELECTOR = 'TAI-Key-Selector';\nexport const TAI64N_HEADER_LEAP_SECONDS = 'TAI-Leap-Seconds';\nexport const TAI64N_HEADER_NONCE = 'TAI-Nonce';\nexport const TAI64N_HEADER_SIGNATURE = 'TAI-Signature';\n\nexport const TAI64_EPOCH_HI = 0x40_00_00_00;\n","import {\n  TAI64N_HEADER_KEY_SELECTOR,\n  TAI64N_HEADER_LEAP_SECONDS,\n  TAI64N_HEADER_NONCE,\n  TAI64N_HEADER_SIGNATURE,\n} from './const';\n\n// `Access-Control-Allow-Methods` (Fetch) is the list\n// of methods JS would ever preflight, so `OPTIONS` is\n// omitted. This is intentionally narrower than the\n// `Allow` header (RFC 9110 §9.3.7 method discovery,\n// `GET, HEAD, OPTIONS`) the handler itself emits.\nconst CORS_ALLOW_METHODS = 'GET, HEAD';\nconst CORS_ALLOW_HEADERS = TAI64N_HEADER_NONCE;\nconst CORS_EXPOSE_HEADERS = [\n  TAI64N_HEADER_LEAP_SECONDS,\n  TAI64N_HEADER_NONCE,\n  TAI64N_HEADER_KEY_SELECTOR,\n  TAI64N_HEADER_SIGNATURE,\n].join(', ');\n// Spec §4.2 SHOULDs at least 600s; 10 minutes is the\n// floor the spec example uses and keeps high-traffic\n// cross-origin clients off a pre-flight per fetch.\nconst CORS_MAX_AGE = '600';\n\n/**\n * The three CORS header maps the handler splices into\n * responses, keyed by response kind.\n *\n * - `preflight` — added to `OPTIONS 200` replies.\n * - `response` — added to successful `GET` / `HEAD`\n *   replies; carries `Access-Control-Expose-Headers`\n *   so browser JS can read the `TAI-*` headers.\n * - `error` — added to `405` replies; just the origin\n *   header (and `Vary` when scoped).\n */\nexport type CORSHeaderSets = {\n  error: Record<string, string>\n  preflight: Record<string, string>\n  response: Record<string, string>\n};\n\n/**\n * Pre-bake the three CORS header maps the handler\n * splices into responses, keyed by response kind.\n * `cors === false` collapses every map to `{}` so the\n * spread is a no-op; missing or empty input falls back\n * to `'*'`; `cors === '*'` skips `Vary: Origin` (a\n * wildcard does not vary by origin); a scoped origin\n * adds `Vary: Origin` so caches can keep per-origin\n * variants distinct.\n */\nexport const buildCORSHeaders = (\n  cors: false | string | undefined,\n): CORSHeaderSets => {\n  if (cors === false) {\n    return { error: {}, preflight: {}, response: {} };\n  }\n  const origin = cors || '*';\n  const vary: Record<string, string> =\n    origin === '*' ? {} : { vary: 'Origin' };\n  return {\n    error: {\n      'access-control-allow-origin': origin,\n      ...vary,\n    },\n    preflight: {\n      'access-control-allow-origin': origin,\n      'access-control-allow-methods': CORS_ALLOW_METHODS,\n      'access-control-allow-headers': CORS_ALLOW_HEADERS,\n      'access-control-expose-headers': CORS_EXPOSE_HEADERS,\n      'access-control-max-age': CORS_MAX_AGE,\n      ...vary,\n    },\n    response: {\n      'access-control-allow-origin': origin,\n      'access-control-expose-headers': CORS_EXPOSE_HEADERS,\n      ...vary,\n    },\n  };\n};\n","// cspell:words IERS\n\nimport { TAI64N_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.1.\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 non-integer, negative,\n * or exceeds {@link TAI_LEAP_SECONDS_MAX}.\n */\nexport const asLeapSeconds = (\n  value: number,\n): LeapSeconds | undefined => {\n  if (\n    !Number.isInteger(value) ||\n    value < 0 ||\n    value > TAI_LEAP_SECONDS_MAX\n  ) 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.1\n * collapsed into one verdict.\n */\nexport const extractLeapSeconds = (\n  headers: Headers,\n): LeapSeconds | undefined => {\n  const raw = headers.get(TAI64N_HEADER_LEAP_SECONDS);\n  if (!raw || !DECIMAL_INTEGER.test(raw)) return undefined;\n  return asLeapSeconds(Number(raw));\n};\n","import { TAI64N_HEADER_NONCE } from './const';\n\n/**\n * Lower bound on `TAI-Nonce` field-value octets. A\n * field shorter than this is treated as absent (spec\n * §5.2). sf-binary is ASCII-only — the string length\n * equals the octet count.\n */\nexport const NONCE_MIN_OCTETS = 14;\n\n/**\n * Upper bound on `TAI-Nonce` field-value octets. A\n * field longer than this is treated as absent (spec\n * §5.2).\n */\nexport const NONCE_MAX_OCTETS = 174;\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 excluded — a\n * zero-length nonce is treated as absent per spec\n * §5.2. The alphabet contains no `,`, so a duplicated\n * field (joined by the Web `Headers` API with `,`)\n * fails the same check.\n */\nconst 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\ndeclare const NonceBrand: unique symbol;\n\n/**\n * `string` that has been confirmed to satisfy the\n * sf-binary syntax of RFC 9651 §3.3.5 and the\n * `[NONCE_MIN_OCTETS, NONCE_MAX_OCTETS]` length range\n * required by spec §5.2. Construct only via\n * {@link asNonce} or {@link extractNonce}; the brand\n * prevents arbitrary strings from reaching the\n * signing path.\n */\nexport type Nonce = string & { readonly [NonceBrand]: never };\n\n/**\n * Brand `value` as a {@link Nonce} when it satisfies\n * sf-binary syntax (RFC 9651 §3.3.5) and falls inside\n * `[NONCE_MIN_OCTETS, NONCE_MAX_OCTETS]`. Returns\n * `undefined` for anything else — every \"treat as\n * absent\" case in spec §5.2 collapsed into one\n * verdict.\n */\nexport const asNonce = (value: string): Nonce | undefined => {\n  if (\n    !value ||\n    value.length < NONCE_MIN_OCTETS ||\n    value.length > NONCE_MAX_OCTETS ||\n    !SF_BINARY_PATTERN.test(value)\n  ) return undefined;\n  return value as Nonce;\n};\n\n/**\n * Extract a usable `TAI-Nonce` from request headers.\n * Returns `undefined` when the field is missing or\n * fails {@link asNonce} validation.\n */\nexport const extractNonce = (headers: Headers): Nonce | undefined => {\n  const value = headers.get(TAI64N_HEADER_NONCE);\n  return value === null ? undefined : asNonce(value);\n};\n","import { TAI64_EPOCH_HI } from './const';\nimport { TAI_LEAP_SECONDS } from './leap-seconds';\n\ntype timestamp = {\n  nano: number\n  sec: number\n\n  offset?: number\n};\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\nexport const now = (): timestamp => {\n  const utc = Date.now();\n  return fromUTC(utc);\n};\n\nexport const tai64nLabel = (value?: timestamp): string => {\n  const { sec, nano } = value ?? now();\n\n  const secHi = Math.trunc(sec / u32Range) + TAI64_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\nexport const tai64nLabelFromUTC = (utc: number): string => tai64nLabel(fromUTC(utc));\n\nconst u32Range = 0x1_00_00_00_00;\n","import { assertValidSelector, type Signer } from '@kagal/ed25519-secret';\n\nimport {\n  TAI64N_CONTENT_LENGTH,\n  TAI64N_CONTENT_TYPE,\n  TAI64N_HEADER_KEY_SELECTOR,\n  TAI64N_HEADER_LEAP_SECONDS,\n  TAI64N_HEADER_NONCE,\n  TAI64N_HEADER_SIGNATURE,\n} from './const';\nimport { buildCORSHeaders } from './cors';\nimport { type LeapSeconds, TAI_LEAP_SECONDS } from './leap-seconds';\nimport { extractNonce, type Nonce } from './nonce';\nimport { tai64nLabel } from './utils';\n\nconst ALLOW_HEADER = 'GET, HEAD, OPTIONS';\n\nconst textEncoder = new TextEncoder();\n\n/**\n * Domain-separation tag prepended to every signed\n * payload. Versioned so a v2 protocol can use the same\n * key without colliding with v1 signatures, and\n * NUL-terminated so the boundary between tag and\n * label is unambiguous.\n */\nconst DOMAIN_SEPARATOR = textEncoder.encode('taistamp-v1\\0');\n\nconst asBytes = (source: BufferSource): Uint8Array => {\n  if (source instanceof Uint8Array) {\n    return source;\n  }\n  if (ArrayBuffer.isView(source)) {\n    return new Uint8Array(\n      source.buffer,\n      source.byteOffset,\n      source.byteLength,\n    );\n  }\n  return new Uint8Array(source);\n};\n\n/**\n * Encode `source` as a Structured Field Value sf-binary\n * item per [RFC 9651 §3.3.5]: standard base64 with `=`\n * padding, wrapped in a leading and trailing colon.\n *\n * @see {@link https://www.rfc-editor.org/rfc/rfc9651#name-byte-sequences}\n */\nconst encodeStructuredBinary = (source: BufferSource): string => {\n  // Spread is safe for the 64-byte signatures handled\n  // here; revisit if larger payloads ever land.\n  const bytes = asBytes(source);\n  const standard = btoa(String.fromCodePoint(...bytes));\n  return `:${standard}:`;\n};\n\n/**\n * Compose the byte sequence covered by a TAI-Signature.\n *\n * @param label - the 25-byte TAI64N label string the\n *   server is returning\n * @param leapSeconds - the leap-seconds count the server\n *   advertises in `TAI-Leap-Seconds`\n * @param selector - the key selector the server\n *   advertises in `TAI-Key-Selector`; verifiers use\n *   this to look up the public key in DNS at\n *   `<selector>._taistamp.<host>`\n * @param nonce - the client-supplied nonce, echoed\n *   verbatim in `TAI-Nonce`; brand a verifier-side\n *   string with {@link asNonce} before passing it in\n * @returns the byte sequence verifiers reconstruct\n *   from the response and pass to their public-key\n *   verify routine. The framing is the\n *   domain-separation tag (`taistamp-v1` plus a\n *   trailing NUL byte), then the label bytes, then\n *   the leap-seconds count as a 4-byte big-endian\n *   unsigned integer, then a 1-byte selector length,\n *   then the selector bytes, then the nonce bytes.\n *\n * @remarks\n * Binding the selector into the signed payload stops a\n * downgrade attacker from rewriting `TAI-Key-Selector`\n * to point at a compromised or weaker key — the\n * signature would no longer verify under that key.\n * `leapSeconds` is encoded as a 4-byte big-endian\n * unsigned integer; the selector is length-prefixed by\n * a single byte (selectors are ≤ 63 chars per\n * {@link newTaistampHandler}'s validation).\n */\nexport const composeSignaturePayload = (\n  label: string,\n  leapSeconds: LeapSeconds,\n  selector: string,\n  nonce: Nonce,\n): ArrayBuffer => {\n  const labelBytes = textEncoder.encode(label);\n  const selectorBytes = textEncoder.encode(selector);\n  const nonceBytes = textEncoder.encode(nonce);\n\n  const buffer = new ArrayBuffer(\n    DOMAIN_SEPARATOR.length +\n    labelBytes.length +\n    4 +\n    1 +\n    selectorBytes.length +\n    nonceBytes.length,\n  );\n  const view = new Uint8Array(buffer);\n\n  let offset = 0;\n  view.set(DOMAIN_SEPARATOR, offset);\n  offset += DOMAIN_SEPARATOR.length;\n  view.set(labelBytes, offset);\n  offset += labelBytes.length;\n  new DataView(buffer).setUint32(offset, leapSeconds, false);\n  offset += 4;\n  view[offset] = selectorBytes.length;\n  offset += 1;\n  view.set(selectorBytes, offset);\n  offset += selectorBytes.length;\n  view.set(nonceBytes, offset);\n\n  return buffer;\n};\n\n/**\n * Configuration for {@link newTaistampHandler}.\n *\n * @remarks\n * `signer` and `selector` are co-required: pass both\n * to enable authenticated responses, or neither for\n * an unsigned handler. Passing only one is rejected\n * at construction time — without the selector\n * verifiers cannot find the key in DNS, and a\n * selector without a signer is a misconfiguration.\n */\nexport interface TaistampHandlerConfig {\n  /**\n   * Key selector advertised in the `TAI-Key-Selector`\n   * response header and bound into the signed payload.\n   * Verifiers look up the public key at\n   * `<selector>._taistamp.<host>` in DNS.\n   *\n   * Must match `[A-Za-z][A-Za-z0-9_-]{0,62}` (a single\n   * DNS label starting with a letter, using\n   * DKIM-compatible characters and a valid sf-token);\n   * rotate by changing the selector and publishing a\n   * new TXT record.\n   */\n  selector?: string\n\n  /**\n   * {@link Signer} that produces `TAI-Signature` over\n   * the framed payload from {@link composeSignaturePayload}.\n   * Without a signer the nonce is still echoed but the\n   * response is unsigned.\n   */\n  signer?: Signer\n\n  /**\n   * CORS origin policy. Defaults to `'*'`; pass `false`\n   * to disable CORS entirely, or a specific origin\n   * (e.g. `'https://example.com'`) to scope the policy.\n   *\n   * Every response (`GET` / `HEAD` / `OPTIONS` / `405`)\n   * gains `Access-Control-Allow-Origin`; pre-flight\n   * `OPTIONS` also carries `-Allow-Methods`,\n   * `-Allow-Headers`, `-Expose-Headers`, and\n   * `-Max-Age: 600` per spec §4.2; success\n   * `GET` / `HEAD` carry `-Expose-Headers` so browser\n   * JS can read the `TAI-*` response headers. A\n   * non-`'*'` value adds `Vary: Origin` so caches can\n   * keep per-origin variants distinct.\n   *\n   * Disabling CORS does not affect method discovery:\n   * `OPTIONS` is still answered with `200` and\n   * `Allow: GET, HEAD, OPTIONS` per RFC 9110 §9.3.7.\n   */\n  cors?: false | string\n}\n\n/**\n * Validate a {@link TaistampHandlerConfig} and return\n * it unchanged when every field is well-formed.\n * Throws `TypeError` otherwise so misconfiguration\n * surfaces at handler construction rather than on the\n * first request.\n *\n * @throws TypeError if `signer` and `selector` are not\n *   both set or both unset, or if `selector` does not\n *   match `[A-Za-z][A-Za-z0-9_-]{0,62}`.\n */\nconst validateHandlerConfig = (\n  config: TaistampHandlerConfig,\n): TaistampHandlerConfig => {\n  const { cors, selector, signer } = config;\n\n  if ((signer === undefined) !== (selector === undefined)) {\n    throw new TypeError(\n      'newTaistampHandler: signer and selector must be set together',\n    );\n  }\n  if (cors !== undefined && cors !== false && typeof cors !== 'string') {\n    throw new TypeError(\n      'newTaistampHandler: cors must be false or a string origin',\n    );\n  }\n  if (selector !== undefined) {\n    assertValidSelector(selector, 'newTaistampHandler');\n  }\n\n  return config;\n};\n\n/**\n * Validate a {@link TaistampHandlerConfig} and derive\n * the construction-time state the handler closure\n * captures: the pre-baked CORS header maps and an\n * `addSignature` helper that mutates a response\n * `Headers` to carry `TAI-Key-Selector` and\n * `TAI-Signature` over the framed payload, present\n * only when both `signer` and `selector` are\n * configured. Validation is delegated to\n * {@link validateHandlerConfig}.\n *\n * @throws TypeError per {@link validateHandlerConfig}.\n */\nconst fromHandlerConfig = (config: TaistampHandlerConfig) => {\n  const { cors, selector, signer } = validateHandlerConfig(config);\n\n  const corsHeaders = buildCORSHeaders(cors);\n\n  const addSignature = selector !== undefined && signer !== undefined ?\n    async (\n      headers: Headers,\n      label: string,\n      nonce: Nonce,\n    ): Promise<void> => {\n      const payload = composeSignaturePayload(\n        label, TAI_LEAP_SECONDS, selector, nonce,\n      );\n      const signature = await signer.sign(payload);\n      headers.set(TAI64N_HEADER_KEY_SELECTOR, selector);\n      headers.set(\n        TAI64N_HEADER_SIGNATURE,\n        encodeStructuredBinary(signature),\n      );\n    } :\n    undefined;\n\n  return { addSignature, corsHeaders };\n};\n\n/**\n * Build a handler for `/.well-known/taistamp`.\n *\n * @param config - optional {@link TaistampHandlerConfig}\n * @returns an `async (request) => Response` callable\n *   directly as a Web `fetch` handler or as a Hono\n *   route handler.\n *\n * @throws TypeError if `signer` and `selector` are not\n *   both set or both unset, or if `selector` does not\n *   match `[A-Za-z][A-Za-z0-9_-]{0,62}`.\n *\n * @remarks\n * Behaviour:\n *\n * - `GET` / `HEAD` — body is a fresh 25-byte TAI64N\n *   label (`HEAD` omits the body). Response headers:\n *   Content-Type `application/tai64n`, Content-Length\n *   `25`, Cache-Control `no-store`, plus\n *   `TAI-Leap-Seconds` carrying the current count.\n * - `OPTIONS` — `200` with `Allow: GET, HEAD, OPTIONS`.\n *   When CORS is enabled (the default) the response\n *   also carries `Access-Control-Allow-*` and\n *   `-Expose-Headers` per\n *   {@link TaistampHandlerConfig.cors}. `OPTIONS` is\n *   never signed.\n * - Any other method — `405 Method Not Allowed` with\n *   `Allow: GET, HEAD, OPTIONS`.\n * - Request `TAI-Nonce` — on `GET`, the value is echoed\n *   verbatim in the response. A missing, empty,\n *   duplicated, structurally malformed, or out-of-range\n *   (14..174 octets) field is treated as absent (no\n *   echo, no signature) per spec §5.2 — see\n *   {@link extractNonce}. `HEAD`, `OPTIONS`, and `405`\n *   responses never carry `TAI-Nonce` per spec §4.1.\n * - Request `TAI-Nonce` *and* `signer` configured *and*\n *   the request method is `GET` — adds\n *   `TAI-Key-Selector` and `TAI-Signature` (sf-binary)\n *   over the bytes produced by\n *   {@link composeSignaturePayload}. The\n *   domain-separation tag means the same key cannot\n *   be tricked into producing valid signatures for\n *   other protocols. `HEAD`, `OPTIONS`, and `405`\n *   responses are never signed.\n *\n * The corresponding public key is expected to be\n * published out-of-band as a DNS TXT record at\n * `<selector>._taistamp.<host>` — verifiers fetch the\n * key by selector so the operator can rotate keys by\n * publishing a new selector while the old one is\n * still cached.\n *\n * @see {@link https://cr.yp.to/libtai/tai64.html} for\n *   TAI64N format\n */\nexport const newTaistampHandler = (\n  config: TaistampHandlerConfig = {},\n): ((request: Request) => Promise<Response>) => {\n  const { addSignature, corsHeaders } = fromHandlerConfig(config);\n\n  return async (request) => {\n    if (request.method === 'OPTIONS') {\n      return new Response(undefined, {\n        status: 200,\n        headers: { allow: ALLOW_HEADER, ...corsHeaders.preflight },\n      });\n    }\n\n    if (request.method !== 'GET' && request.method !== 'HEAD') {\n      return new Response(undefined, {\n        status: 405,\n        headers: { allow: ALLOW_HEADER, ...corsHeaders.error },\n      });\n    }\n\n    const nonce = extractNonce(request.headers);\n    const label = tai64nLabel();\n\n    const headers = new Headers({\n      'cache-control': 'no-store',\n      'content-length': String(TAI64N_CONTENT_LENGTH),\n      'content-type': TAI64N_CONTENT_TYPE,\n      [TAI64N_HEADER_LEAP_SECONDS]: String(TAI_LEAP_SECONDS),\n      ...corsHeaders.response,\n    });\n\n    if (nonce && request.method === 'GET') {\n      headers.set(TAI64N_HEADER_NONCE, nonce);\n      if (addSignature) {\n        await addSignature(headers, label, nonce);\n      }\n    }\n\n    const body = request.method === 'HEAD' ? undefined : label;\n    return new Response(body, { status: 200, headers });\n  };\n};\n","import pkg from '../package.json' with { type: 'json' };\n\n/** Package version from package.json. */\nexport const VERSION: string = pkg.version;\n\nexport {\n  newSigner as newEd25519Signer,\n  type Signer,\n} from '@kagal/ed25519-secret';\n\nexport * from './const';\nexport {\n  composeSignaturePayload,\n  newTaistampHandler,\n  type TaistampHandlerConfig,\n} from './handler';\nexport {\n  asLeapSeconds,\n  extractLeapSeconds,\n  type LeapSeconds,\n  TAI_LEAP_SECONDS,\n  TAI_LEAP_SECONDS_MAX,\n} from './leap-seconds';\nexport {\n  asNonce,\n  type Nonce,\n} from './nonce';\nexport {\n  fromUTC,\n  now,\n  tai64nLabel,\n  tai64nLabelFromUTC,\n} from './utils';\n"],"mappings":";;ACAA,MAAa,gBAAgB;AAG7B,MAAa,cAAc;AAE3B,MAAa,sBAAsB;AACnC,MAAa,wBAAwB;AAErC,MAAa,6BAA6B;AAC1C,MAAa,6BAA6B;AAC1C,MAAa,sBAAsB;AACnC,MAAa,0BAA0B;AAEvC,MAAa,iBAAiB;ACD9B,MAAM,qBAAqB;AAC3B,MAAM,qBAAqB;AAC3B,MAAM,sBAAsB;CAC1B;CACA;CACA;CACA;AACF,EAAE,KAAK,IAAI;AAIX,MAAM,eAAe;;;;;;;;;;EA6BrB,OAAa;GAGX,+BACS;GAAE,GAAA;EAAW;EAAe,WAAW;GAAE,+BAAA;GAElD,gCAAuB;GACvB,gCACoB;GACpB,iCAAO;GACL,0BAAO;GACL,GAAA;;EAEF,UAAA;GACA,+BAAW;GACT,iCAA+B;GAC/B,GAAA;;;;MAMF,uBAAU;MAER,iBAAA,UAAA;KACA,CAAG,OAAA,UAAA,KAAA,KAAA,QAAA,KAAA,QAAA,YAAA,OAAA,KAAA;QACL;;;;;;;;;AC/CJ,MAAa,oBACX;MAOA,WAAO,UAAA;CACT,IAAA,CAAA,SAAA,MAAA,SAAA,MAAA,MAAA,SAAA,OAAA,CAAA,kBAAA,KAAA,KAAA,GAAA,OAAA,KAAA;;;;;;;;;;;EAcA,QAAa;;;;;;;;;CAUb,MAAM,QAAA,MAAA;;;;;;;AAUN,MAAa,mBAAA,YACX,OAC4B,eAAA;MAC5B,WAAY,WAAY;CACxB,IAAI,kBAAS,YAAqB,OAAM;CACxC,IAAA,YAAO,OAAc,MAAO,GAAI,OAAA,IAAA,WAAA,OAAA,QAAA,OAAA,YAAA,OAAA,UAAA;CAClC,OAAA,IAAA,WAAA,MAAA;;;;;;ACxEA,MAAa,2BAAmB,OAAA,aAAA,UAAA,UAAA;;;;;;CAOhC,IAAA,SAAa;;;;;;;;;;CAWb,UAAM,cAAA;;;;;;;;CAwBN,IAAA,aAAwB,KAAA,GAAA,oBAAqC,UAAA,oBAAA;CAC3D,OACG;;;;;;;GAaL,MAAa,UAAA,wBAAwD,OAAA,IAAA,UAAA,KAAA;GACnE,MAAM,YAAQ,MAAY,OAAA,KAAA,OAAmB;GAC7C,QAAO,IAAA,4BAAqC,QAAK;GACnD,QAAA,IAAA,yBAAA,uBAAA,SAAA,CAAA;;EC1DA;CAIE;;MAAoB,sBAAA,SAAA,CAAA,MAAA;CAAyB,MAAA,EAAA,cAAA,gBAAA,kBAAA,MAAA;CAC/C,OAAA,OAAA,YAAA;EAEA,IAAa,QAAA,WAAuB,WAAA,OAAA,IAAA,SAAA,KAAA,GAAA;GAElC,QAAO;GACT,SAAA;IAEA,OAAa;IACX,GAAM,YAAO;GAEb;EACA,CAAA;EAMA,IAAA,QAJiB,WAAM,SAAa,QAAS,WAC5B,QAAM,OAAW,IAAE,SAAY,KAGnB,GAFb;GAGlB,QAAA;GAEA,SAAa;IAEb,OAAM;;GCtBN;EAEA,CAAA;;;;;;;;GASA,GAAM,YAAA;EAEN,CAAA;EACE,IAAI,SAAA,QAAkB,WAAA,OACpB;GAEF,QAAI,IAAA,qBACF,KAAO;GAMT,IAAA,cAAW,MAAW,aAAM,SAAA,OAAA,KAAA;EAC9B;;;;;;;;MAcE,UADiB"}
+{"version":3,"file":"index.mjs","names":["pkg.version"],"sources":["../package.json","../src/const.ts","../src/cors.ts","../src/leap-seconds.ts","../src/nonce.ts","../src/utils.ts","../src/handler.ts","../src/index.ts"],"sourcesContent":["","export const TAISTAMP_PATH = '/.well-known/taistamp';\n\n/** @deprecated Renamed to {@link TAISTAMP_PATH}. */\nexport const TAI64N_PATH = TAISTAMP_PATH;\n\nexport const TAI64N_CONTENT_TYPE = 'application/tai64n';\nexport const TAI64N_CONTENT_LENGTH = 1 + 16 + 8; // '@' + sec (16 hex chars) + nano (8 hex chars)\n\nexport const TAI64N_HEADER_KEY_SELECTOR = 'TAI-Key-Selector';\nexport const TAI64N_HEADER_LEAP_SECONDS = 'TAI-Leap-Seconds';\nexport const TAI64N_HEADER_NONCE = 'TAI-Nonce';\nexport const TAI64N_HEADER_SIGNATURE = 'TAI-Signature';\n\nexport const TAI64_EPOCH_HI = 0x40_00_00_00;\n","import {\n  TAI64N_HEADER_KEY_SELECTOR,\n  TAI64N_HEADER_LEAP_SECONDS,\n  TAI64N_HEADER_NONCE,\n  TAI64N_HEADER_SIGNATURE,\n} from './const';\n\n// `Access-Control-Allow-Methods` (Fetch) is the list\n// of methods JS would ever preflight, so `OPTIONS` is\n// omitted. This is intentionally narrower than the\n// `Allow` header (RFC 9110 §9.3.7 method discovery,\n// `GET, HEAD, OPTIONS`) the handler itself emits.\nconst CORS_ALLOW_METHODS = 'GET, HEAD';\nconst CORS_ALLOW_HEADERS = TAI64N_HEADER_NONCE;\nconst CORS_EXPOSE_HEADERS = [\n  TAI64N_HEADER_LEAP_SECONDS,\n  TAI64N_HEADER_NONCE,\n  TAI64N_HEADER_KEY_SELECTOR,\n  TAI64N_HEADER_SIGNATURE,\n].join(', ');\n// Spec §5.2 SHOULDs at least 600s; 10 minutes is the\n// floor the spec example uses and keeps high-traffic\n// cross-origin clients off a pre-flight per fetch.\nconst CORS_MAX_AGE = '600';\n\n/**\n * The three CORS header maps the handler splices into\n * responses, keyed by response kind.\n *\n * - `preflight` — added to `OPTIONS 200` replies.\n * - `response` — added to successful `GET` / `HEAD`\n *   replies; carries `Access-Control-Expose-Headers`\n *   so browser JS can read the `TAI-*` headers.\n * - `error` — added to `405` replies; just the origin\n *   header (and `Vary` when scoped).\n */\nexport type CORSHeaderSets = {\n  error: Record<string, string>\n  preflight: Record<string, string>\n  response: Record<string, string>\n};\n\n/**\n * Pre-bake the three CORS header maps the handler\n * splices into responses, keyed by response kind.\n * `cors === false` collapses every map to `{}` so the\n * spread is a no-op; missing or empty input falls back\n * to `'*'`; `cors === '*'` skips `Vary: Origin` (a\n * wildcard does not vary by origin); a scoped origin\n * adds `Vary: Origin` so caches can keep per-origin\n * variants distinct.\n */\nexport const buildCORSHeaders = (\n  cors: false | string | undefined,\n): CORSHeaderSets => {\n  if (cors === false) {\n    return { error: {}, preflight: {}, response: {} };\n  }\n  const origin = cors || '*';\n  const vary: Record<string, string> =\n    origin === '*' ? {} : { vary: 'Origin' };\n  return {\n    error: {\n      'access-control-allow-origin': origin,\n      ...vary,\n    },\n    preflight: {\n      'access-control-allow-origin': origin,\n      'access-control-allow-methods': CORS_ALLOW_METHODS,\n      'access-control-allow-headers': CORS_ALLOW_HEADERS,\n      'access-control-expose-headers': CORS_EXPOSE_HEADERS,\n      'access-control-max-age': CORS_MAX_AGE,\n      ...vary,\n    },\n    response: {\n      'access-control-allow-origin': origin,\n      'access-control-expose-headers': CORS_EXPOSE_HEADERS,\n      ...vary,\n    },\n  };\n};\n","// cspell:words IERS\n\nimport { TAI64N_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 non-integer, negative,\n * or exceeds {@link TAI_LEAP_SECONDS_MAX}.\n */\nexport const asLeapSeconds = (\n  value: number,\n): LeapSeconds | undefined => {\n  if (\n    !Number.isInteger(value) ||\n    value < 0 ||\n    value > TAI_LEAP_SECONDS_MAX\n  ) 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(TAI64N_HEADER_LEAP_SECONDS);\n  if (!raw || !DECIMAL_INTEGER.test(raw)) return undefined;\n  return asLeapSeconds(Number(raw));\n};\n","import { TAI64N_HEADER_NONCE } from './const';\n\n/**\n * Wire-form lower bound on `TAI-Nonce`. Spec §5.4 sets\n * the normative bound on decoded length (≥ 7 octets);\n * 14 is the smallest wire form (`:` + 12 base64 chars\n * + `:`) that can decode to 7 octets, so the wire\n * check rejects undersize input before base64 decoding.\n * sf-binary is ASCII-only — the string length equals\n * the octet count.\n */\nexport const NONCE_MIN_OCTETS = 14;\n\n/**\n * Wire-form upper bound on `TAI-Nonce`. Spec §5.4 sets\n * the normative bound on decoded length (≤ 129 octets);\n * 174 is the longest wire form (`:` + 172 base64 chars\n * + `:`) whose decoded payload stays within 129 octets,\n * so the wire check rejects oversize input before\n * base64 decoding.\n */\nexport const NONCE_MAX_OCTETS = 174;\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 excluded — a\n * zero-length nonce is treated as absent per spec\n * §5.4. The alphabet contains no `,`, so a duplicated\n * field (joined by the Web `Headers` API with `,`)\n * fails the same check.\n */\nconst 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\ndeclare const NonceBrand: unique symbol;\n\n/**\n * `string` that has been confirmed to satisfy the\n * sf-binary syntax of RFC 9651 §3.3.5 and to fall\n * inside the wire-form length range\n * `[NONCE_MIN_OCTETS, NONCE_MAX_OCTETS]` — the\n * pre-decode form of spec §5.4's normative\n * decoded-length bound of 7..129 octets. Construct\n * only via {@link asNonce} or {@link extractNonce};\n * the brand prevents arbitrary strings from reaching\n * the signing path.\n */\nexport type Nonce = string & { readonly [NonceBrand]: never };\n\n/**\n * Brand `value` as a {@link Nonce} when it satisfies\n * sf-binary syntax (RFC 9651 §3.3.5) and falls inside\n * `[NONCE_MIN_OCTETS, NONCE_MAX_OCTETS]` — the wire\n * range equivalent to spec §5.4's normative\n * decoded-length bound of 7..129 octets. Returns\n * `undefined` for anything else — every \"treat as\n * absent\" case in spec §5.4 collapsed into one\n * verdict.\n */\nexport const asNonce = (value: string): Nonce | undefined => {\n  if (\n    !value ||\n    value.length < NONCE_MIN_OCTETS ||\n    value.length > NONCE_MAX_OCTETS ||\n    !SF_BINARY_PATTERN.test(value)\n  ) return undefined;\n  return value as Nonce;\n};\n\n/**\n * Extract a usable `TAI-Nonce` from request headers.\n * Returns `undefined` when the field is missing or\n * fails {@link asNonce} validation.\n */\nexport const extractNonce = (headers: Headers): Nonce | undefined => {\n  const value = headers.get(TAI64N_HEADER_NONCE);\n  return value === null ? undefined : asNonce(value);\n};\n","import { TAI64_EPOCH_HI } from './const';\nimport { TAI_LEAP_SECONDS } from './leap-seconds';\n\ntype timestamp = {\n  nano: number\n  sec: number\n\n  offset?: number\n};\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\nexport const now = (): timestamp => {\n  const utc = Date.now();\n  return fromUTC(utc);\n};\n\nexport const tai64nLabel = (value?: timestamp): string => {\n  const { sec, nano } = value ?? now();\n\n  const secHi = Math.trunc(sec / u32Range) + TAI64_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\nexport const tai64nLabelFromUTC = (utc: number): string => tai64nLabel(fromUTC(utc));\n\nconst u32Range = 0x1_00_00_00_00;\n","import {\n  assertValidSelector,\n  decodeBase64,\n  encodeBase64,\n  type Signer,\n} from '@kagal/ed25519-secret';\n\nimport {\n  TAI64N_CONTENT_LENGTH,\n  TAI64N_CONTENT_TYPE,\n  TAI64N_HEADER_KEY_SELECTOR,\n  TAI64N_HEADER_LEAP_SECONDS,\n  TAI64N_HEADER_NONCE,\n  TAI64N_HEADER_SIGNATURE,\n} from './const';\nimport { buildCORSHeaders } from './cors';\nimport { type LeapSeconds, TAI_LEAP_SECONDS } from './leap-seconds';\nimport { extractNonce, type Nonce } from './nonce';\nimport { tai64nLabel } from './utils';\n\nconst ALLOW_HEADER = 'GET, HEAD, OPTIONS';\n\nconst textEncoder = new TextEncoder();\n\n/**\n * Domain-separation tag prepended to every signed\n * payload. Versioned so a v2 protocol can use the same\n * key without colliding with v1 signatures, and\n * NUL-terminated so the boundary between tag and\n * label is unambiguous.\n */\nconst DOMAIN_SEPARATOR = textEncoder.encode('taistamp-v1\\0');\n\n/**\n * Compose the byte sequence covered by a TAI-Signature.\n *\n * @param label - the 25-byte TAI64N label string the\n *   server is returning\n * @param leapSeconds - the leap-seconds count the server\n *   advertises in `TAI-Leap-Seconds`\n * @param selector - the key selector the server\n *   advertises in `TAI-Key-Selector`; verifiers use\n *   this to look up the public key in DNS at\n *   `<selector>._taistamp.<host>`\n * @param nonce - the client-supplied nonce, echoed\n *   verbatim in `TAI-Nonce`; brand a verifier-side\n *   string with {@link asNonce} before passing it in\n * @returns the byte sequence verifiers reconstruct\n *   from the response and pass to their public-key\n *   verify routine. The framing is the\n *   domain-separation tag (`taistamp-v1` plus a\n *   trailing NUL byte), then the label bytes, then\n *   the leap-seconds count as a 4-byte big-endian\n *   unsigned integer, then a 1-byte selector length,\n *   then the selector bytes, then the decoded sf-binary\n *   octets of the nonce (spec §6.1 — the wire\n *   `:base64:` framing is not signed).\n *\n * @remarks\n * Binding the selector into the signed payload stops a\n * downgrade attacker from rewriting `TAI-Key-Selector`\n * to point at a compromised or weaker key — the\n * signature would no longer verify under that key.\n * `leapSeconds` is encoded as a 4-byte big-endian\n * unsigned integer; the selector is length-prefixed by\n * a single byte (selectors are ≤ 63 chars per\n * {@link newTaistampHandler}'s validation).\n */\nexport const composeSignaturePayload = (\n  label: string,\n  leapSeconds: LeapSeconds,\n  selector: string,\n  nonce: Nonce,\n): ArrayBuffer => {\n  const labelBytes = textEncoder.encode(label);\n  const selectorBytes = textEncoder.encode(selector);\n  const nonceBytes = decodeBase64(nonce.slice(1, -1));\n\n  const buffer = new ArrayBuffer(\n    DOMAIN_SEPARATOR.length +\n    labelBytes.length +\n    4 +\n    1 +\n    selectorBytes.length +\n    nonceBytes.length,\n  );\n  const view = new Uint8Array(buffer);\n\n  let offset = 0;\n  view.set(DOMAIN_SEPARATOR, offset);\n  offset += DOMAIN_SEPARATOR.length;\n  view.set(labelBytes, offset);\n  offset += labelBytes.length;\n  new DataView(buffer).setUint32(offset, leapSeconds, false);\n  offset += 4;\n  view[offset] = selectorBytes.length;\n  offset += 1;\n  view.set(selectorBytes, offset);\n  offset += selectorBytes.length;\n  view.set(nonceBytes, offset);\n\n  return buffer;\n};\n\n/**\n * Configuration for {@link newTaistampHandler}.\n *\n * @remarks\n * `signer` and `selector` are co-required: pass both\n * to enable authenticated responses, or neither for\n * an unsigned handler. Passing only one is rejected\n * at construction time — without the selector\n * verifiers cannot find the key in DNS, and a\n * selector without a signer is a misconfiguration.\n */\nexport interface TaistampHandlerConfig {\n  /**\n   * Key selector advertised in the `TAI-Key-Selector`\n   * response header and bound into the signed payload.\n   * Verifiers look up the public key at\n   * `<selector>._taistamp.<host>` in DNS.\n   *\n   * Must match `[A-Za-z][A-Za-z0-9_-]{0,62}` (a single\n   * DNS label starting with a letter, using\n   * DKIM-compatible characters and a valid sf-token);\n   * rotate by changing the selector and publishing a\n   * new TXT record.\n   */\n  selector?: string\n\n  /**\n   * {@link Signer} that produces `TAI-Signature` over\n   * the framed payload from {@link composeSignaturePayload}.\n   * Without a signer the nonce is still echoed but the\n   * response is unsigned.\n   */\n  signer?: Signer\n\n  /**\n   * CORS origin policy. Defaults to `'*'`; pass `false`\n   * to disable CORS entirely, or a specific origin\n   * (e.g. `'https://example.com'`) to scope the policy.\n   *\n   * Every response (`GET` / `HEAD` / `OPTIONS` / `405`)\n   * gains `Access-Control-Allow-Origin`; pre-flight\n   * `OPTIONS` also carries `-Allow-Methods`,\n   * `-Allow-Headers`, `-Expose-Headers`, and\n   * `-Max-Age: 600` per spec §5.2; success\n   * `GET` / `HEAD` carry `-Expose-Headers` so browser\n   * JS can read the `TAI-*` response headers. A\n   * non-`'*'` value adds `Vary: Origin` so caches can\n   * keep per-origin variants distinct.\n   *\n   * Disabling CORS does not affect method discovery:\n   * `OPTIONS` is still answered with `200` and\n   * `Allow: GET, HEAD, OPTIONS` per RFC 9110 §9.3.7.\n   */\n  cors?: false | string\n}\n\n/**\n * Validate a {@link TaistampHandlerConfig} and return\n * it unchanged when every field is well-formed.\n * Throws `TypeError` otherwise so misconfiguration\n * surfaces at handler construction rather than on the\n * first request.\n *\n * @throws TypeError if `signer` and `selector` are not\n *   both set or both unset, or if `selector` does not\n *   match `[A-Za-z][A-Za-z0-9_-]{0,62}`.\n */\nconst validateHandlerConfig = (\n  config: TaistampHandlerConfig,\n): TaistampHandlerConfig => {\n  const { cors, selector, signer } = config;\n\n  if ((signer === undefined) !== (selector === undefined)) {\n    throw new TypeError(\n      'newTaistampHandler: signer and selector must be set together',\n    );\n  }\n  if (cors !== undefined && cors !== false && typeof cors !== 'string') {\n    throw new TypeError(\n      'newTaistampHandler: cors must be false or a string origin',\n    );\n  }\n  if (selector !== undefined) {\n    assertValidSelector(selector, 'newTaistampHandler');\n  }\n\n  return config;\n};\n\n/**\n * Validate a {@link TaistampHandlerConfig} and derive\n * the construction-time state the handler closure\n * captures: the pre-baked CORS header maps and an\n * `addSignature` helper that mutates a response\n * `Headers` to carry `TAI-Key-Selector` and\n * `TAI-Signature` over the framed payload, present\n * only when both `signer` and `selector` are\n * configured. Validation is delegated to\n * {@link validateHandlerConfig}.\n *\n * @throws TypeError per {@link validateHandlerConfig}.\n */\nconst fromHandlerConfig = (config: TaistampHandlerConfig) => {\n  const { cors, selector, signer } = validateHandlerConfig(config);\n\n  const corsHeaders = buildCORSHeaders(cors);\n\n  const addSignature = selector !== undefined && signer !== undefined ?\n    async (\n      headers: Headers,\n      label: string,\n      nonce: Nonce,\n    ): Promise<void> => {\n      const payload = composeSignaturePayload(\n        label, TAI_LEAP_SECONDS, selector, nonce,\n      );\n      const signature = await signer.sign(payload);\n      headers.set(TAI64N_HEADER_KEY_SELECTOR, selector);\n      headers.set(\n        TAI64N_HEADER_SIGNATURE,\n        `:${encodeBase64(new Uint8Array(signature))}:`,\n      );\n    } :\n    undefined;\n\n  return { addSignature, corsHeaders };\n};\n\n/**\n * Build a handler for `/.well-known/taistamp`.\n *\n * @param config - optional {@link TaistampHandlerConfig}\n * @returns an `async (request) => Response` callable\n *   directly as a Web `fetch` handler or as a Hono\n *   route handler.\n *\n * @throws TypeError if `signer` and `selector` are not\n *   both set or both unset, or if `selector` does not\n *   match `[A-Za-z][A-Za-z0-9_-]{0,62}`.\n *\n * @remarks\n * Behaviour:\n *\n * - `GET` / `HEAD` — body is a fresh 25-byte TAI64N\n *   label (`HEAD` omits the body). Response headers:\n *   Content-Type `application/tai64n`, Content-Length\n *   `25`, Cache-Control `no-store`, plus\n *   `TAI-Leap-Seconds` carrying the current count.\n * - `OPTIONS` — `200` with `Allow: GET, HEAD, OPTIONS`.\n *   When CORS is enabled (the default) the response\n *   also carries `Access-Control-Allow-*` and\n *   `-Expose-Headers` per\n *   {@link TaistampHandlerConfig.cors}. `OPTIONS` is\n *   never signed.\n * - Any other method — `405 Method Not Allowed` with\n *   `Allow: GET, HEAD, OPTIONS`.\n * - Request `TAI-Nonce` — on `GET`, the value is echoed\n *   verbatim in the response. A missing, empty,\n *   duplicated, structurally malformed, or\n *   length-out-of-range field is treated as absent (no\n *   echo, no signature) per spec §5.4 — see\n *   {@link extractNonce}. `HEAD`, `OPTIONS`, and `405`\n *   responses never carry `TAI-Nonce` per spec §5.1.\n * - Request `TAI-Nonce` *and* `signer` configured *and*\n *   the request method is `GET` — adds\n *   `TAI-Key-Selector` and `TAI-Signature` (sf-binary)\n *   over the bytes produced by\n *   {@link composeSignaturePayload}. The\n *   domain-separation tag means the same key cannot\n *   be tricked into producing valid signatures for\n *   other protocols. `HEAD`, `OPTIONS`, and `405`\n *   responses are never signed.\n *\n * The corresponding public key is expected to be\n * published out-of-band as a DNS TXT record at\n * `<selector>._taistamp.<host>` — verifiers fetch the\n * key by selector so the operator can rotate keys by\n * publishing a new selector while the old one is\n * still cached.\n *\n * @see {@link https://cr.yp.to/libtai/tai64.html} for\n *   TAI64N format\n */\nexport const newTaistampHandler = (\n  config: TaistampHandlerConfig = {},\n): ((request: Request) => Promise<Response>) => {\n  const { addSignature, corsHeaders } = fromHandlerConfig(config);\n\n  return async (request) => {\n    if (request.method === 'OPTIONS') {\n      return new Response(undefined, {\n        status: 200,\n        headers: { allow: ALLOW_HEADER, ...corsHeaders.preflight },\n      });\n    }\n\n    if (request.method !== 'GET' && request.method !== 'HEAD') {\n      return new Response(undefined, {\n        status: 405,\n        headers: { allow: ALLOW_HEADER, ...corsHeaders.error },\n      });\n    }\n\n    const nonce = extractNonce(request.headers);\n    const label = tai64nLabel();\n\n    const headers = new Headers({\n      'cache-control': 'no-store',\n      'content-length': String(TAI64N_CONTENT_LENGTH),\n      'content-type': TAI64N_CONTENT_TYPE,\n      [TAI64N_HEADER_LEAP_SECONDS]: String(TAI_LEAP_SECONDS),\n      ...corsHeaders.response,\n    });\n\n    if (nonce && request.method === 'GET') {\n      headers.set(TAI64N_HEADER_NONCE, nonce);\n      if (addSignature) {\n        await addSignature(headers, label, nonce);\n      }\n    }\n\n    const body = request.method === 'HEAD' ? undefined : label;\n    return new Response(body, { status: 200, headers });\n  };\n};\n","import pkg from '../package.json' with { type: 'json' };\n\n/** Package version from package.json. */\nexport const VERSION: string = pkg.version;\n\nexport {\n  newSigner as newEd25519Signer,\n  type Signer,\n} from '@kagal/ed25519-secret';\n\nexport * from './const';\nexport {\n  composeSignaturePayload,\n  newTaistampHandler,\n  type TaistampHandlerConfig,\n} from './handler';\nexport {\n  asLeapSeconds,\n  extractLeapSeconds,\n  type LeapSeconds,\n  TAI_LEAP_SECONDS,\n  TAI_LEAP_SECONDS_MAX,\n} from './leap-seconds';\nexport {\n  asNonce,\n  type Nonce,\n} from './nonce';\nexport {\n  fromUTC,\n  now,\n  tai64nLabel,\n  tai64nLabelFromUTC,\n} from './utils';\n"],"mappings":";;ACAA,MAAa,gBAAgB;AAG7B,MAAa,cAAc;AAE3B,MAAa,sBAAsB;AACnC,MAAa,wBAAwB;AAErC,MAAa,6BAA6B;AAC1C,MAAa,6BAA6B;AAC1C,MAAa,sBAAsB;AACnC,MAAa,0BAA0B;AAEvC,MAAa,iBAAiB;ACD9B,MAAM,qBAAqB;AAC3B,MAAM,qBAAqB;AAC3B,MAAM,sBAAsB;CAC1B;CACA;CACA;CACA;AACF,EAAE,KAAK,IAAI;AAIX,MAAM,eAAe;;;;;;;;;;EA6BrB,OAAa;GAGX,+BACS;GAAE,GAAA;EAAW;EAAe,WAAW;GAAE,+BAAA;GAElD,gCAAuB;GACvB,gCACoB;GACpB,iCAAO;GACL,0BAAO;GACL,GAAA;;EAEF,UAAA;GACA,+BAAW;GACT,iCAA+B;GAC/B,GAAA;;;;MAMF,uBAAU;MAER,iBAAA,UAAA;KACA,CAAG,OAAA,UAAA,KAAA,KAAA,QAAA,KAAA,QAAA,YAAA,OAAA,KAAA;QACL;;;;;;;;;AC/CJ,MAAa,oBACX;MAOA,WAAO,UAAA;CACT,IAAA,CAAA,SAAA,MAAA,SAAA,MAAA,MAAA,SAAA,OAAA,CAAA,kBAAA,KAAA,KAAA,GAAA,OAAA,KAAA;;;;;;;;;;;EAcA,QAAa;;;;;;;;;CAUb,MAAM,QAAA,MAAA;;;;;;;AAUN,MAAa,mBAAA,YACX,OAC4B,eAAA;MAEvB,2BAAwB,OAAQ,aAAU,UAAA,UAAA;CAC/C,MAAA,aAAO,YAAwB,OAAC,KAAA;CAClC,MAAA,gBAAA,YAAA,OAAA,QAAA;;;;;;;;;;;CCrEA,KAAa,UAAA,cAAmB;;;;;;;;CAUhC,MAAa,EAAA,MAAA,UAAmB,WAAA;;;;;;;;;CAWhC,OAAM;;;;;;;;;;AA4BN,MAAa,sBAAgD,SAAA,CAAA,MAAA;CAC3D,MACG,EAAA,cACK,gBACN,kBAAM,MACL;CAEH,OAAO,OAAA,YAAA;EACT,IAAA,QAAA,WAAA,WAAA,OAAA,IAAA,SAAA,KAAA,GAAA;;;;;;EAOA,CAAA;EACE,IAAA,QAAM,WAAgB,SAAI,QAAA,WAAmB,QAAA,OAAA,IAAA,SAAA,KAAA,GAAA;GAC7C,QAAO;GACT,SAAA;;ICpEA,GAAa,YAAW;GAItB;EAAS,CAAA;EAAK,MADA,QAAM,aAAQ,QAAA,OAAA;EACR,MAAA,QAAA,YAAA;EAAyB,MAAA,UAAA,IAAA,QAAA;GAC/C,iBAAA;GAEA,kBAAoC,OAAA,EAAA;GAElC,gBADY;IAEd,6BAAA,OAAA,EAAA;GAEA,GAAa,YAAA;EACX,CAAA;EAEA,IAAA,SAAc,QAAK,WAAY,OAAQ;GACvC,QAAM,IAAQ,qBAAM,KAAA;GAMpB,IAAA,cAJuB,MAAS,aAAa,SAI3B,OAHK,KAAA;EAIzB;EAEA,MAAa,OAAA,QAAA,WAAsB,SAAwB,KAAY,IAAA;EAEvE,OAAM,IAAA,SAAW,MAAA;;GCjBjB;EAEA,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kagal/taistamp",
-  "version": "0.0.5",
+  "version": "0.1.0",
   "type": "module",
   "description": "Signed TAI64N timestamps over HTTP",
   "author": "Apptly Software Ltd <oss@apptly.co>",
@@ -16,9 +16,19 @@
   },
   "keywords": [
     "kagal",
+    "cryptography",
+    "ed25519",
+    "eddsa",
+    "handler",
+    "http",
+    "nonce",
+    "rfc8032",
+    "signing",
     "tai64n",
     "taistamp",
-    "typescript"
+    "timestamp",
+    "typescript",
+    "webcrypto"
   ],
   "types": "./dist/index.d.mts",
   "exports": {
@@ -31,7 +41,7 @@
     "dist"
   ],
   "dependencies": {
-    "@kagal/ed25519-secret": "^0.1.2"
+    "@kagal/ed25519-secret": "^0.2.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.13.1",
@@ -43,7 +53,7 @@
     "@vitest/coverage-istanbul": "^4.1.6",
     "eslint": "^9.39.4",
     "npm-run-all2": "^8.0.4",
-    "obuild": "^0.4.34",
+    "obuild": "^0.4.35",
     "publint": "^0.3.21",
     "rimraf": "^6.1.3",
     "typescript": "^6.0.3",