monitor.cert-expiry

export function certExpiry(notAfter: number, now: number, warnDays: number, criticalDays: number): CertExpiry

export type CertExpiryState = "ok" | "warning" | "critical" | "expired";

/** How close a certificate is to expiring. */
export interface CertExpiry {
  readonly state: CertExpiryState;
  /** notAfter - now while valid, 0 once expired */
  readonly secondsLeft: number;
  /** whole days left: floor(secondsLeft / 86400) */
  readonly daysLeft: number;
}

import { certExpiry } from "#fune/monitor.cert-expiry@^1";

import { type CertExpiry } from "./monitor_cert_expiry_types.ts";

/**
 * RFC 5280 makes validity inclusive of notAfter, so a certificate is expired
 * only after that second, not at it. Thresholds compare whole days left with
 * the day counts: fewer than N days (secondsLeft < N * 86400) is exactly
 * floor(secondsLeft / 86400) < N, with no multiplication to overflow.
 */
export function certExpiry(notAfter: number, now: number, warnDays: number, criticalDays: number): CertExpiry {
  if (!Number.isSafeInteger(notAfter) || !Number.isSafeInteger(now)) {
    throw new RangeError(`notAfter and now must be whole seconds, received ${notAfter} and ${now}`);
  }
  if (!Number.isSafeInteger(criticalDays) || criticalDays < 0) {
    throw new RangeError(`criticalDays must be a whole number 0 or more, received ${criticalDays}`);
  }
  if (!Number.isSafeInteger(warnDays) || warnDays < criticalDays) {
    throw new RangeError(`warnDays must be a whole number at least criticalDays (${criticalDays}), received ${warnDays}`);
  }
  if (now > notAfter) return { state: "expired", secondsLeft: 0, daysLeft: 0 };
  const secondsLeft = notAfter - now;
  const daysLeft = Math.floor(secondsLeft / 86400);
  const state = daysLeft < criticalDays ? "critical" : daysLeft < warnDays ? "warning" : "ok";
  return { state, secondsLeft, daysLeft };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add monitor.cert-expiry

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./monitor.cert-expiry-1.0.0-typescript.fune, or fetch it from a terminal with fune pull monitor.cert-expiry@1.0.0:typescript.

The whole function, every language, is one file too: monitor.cert-expiry-1.0.0.fune, 12,501 bytes, sha256 292a46615a892497895595a25acb9d91861d2afa190688786e5cd8eca8dd9720. It installs into a project of any language.

// fune: before monitor.cert-expiry

// fune: after monitor.cert-expiry

// fune: step monitor.cert-expiry after <n|label>

More from the author

- **notAfter is inclusive.** RFC 5280 section 4.1.2.5: "The validity period for a certificate is the period of time from notBefore through notAfter, inclusive." So the certificate is still valid during the notAfter second and is `expired` only when `now > notAfter`. At `now == notAfter`, `secondsLeft` is 0 but the state is not yet expired. - **Thresholds are "fewer than N days"**: critical when `secondsLeft < criticalDays * 86400`, else warning when `secondsLeft < warnDays * 86400`, else ok. Exactly 30 days left with a 30-day warning is still ok. This is computed as `floor(secondsLeft / 86400) < N`, which is the same test with nothing to overflow. - `daysLeft` is whole days, rounded down: 6 days 23 hours is 6. - `secondsLeft` and `daysLeft` are 0 once expired, never negative. - `warnDays` equal to `criticalDays` means no warning stage. With `criticalDays` 0 there is no critical stage, and the last valid second is `ok`; pick at least 1 if you want to hear about it. - The usual settings are 30 and 7 days (Let's Encrypt certificates last 90 days and are renewed at 30 left), or 14 and 3. - `99991231235959Z` (253402300799), which RFC 5280 says marks a certificate with no well-defined expiry, is simply a very distant date and reads `ok`.

## Errors

- `criticalDays must be a whole number 0 or more, received X` - `warnDays must be a whole number at least criticalDays (C), received X` - `notAfter and now must be whole seconds, received A and B`

## Sources

- RFC 5280, Internet X.509 Public Key Infrastructure Certificate and CRL Profile, section 4.1.2.5 Validity: https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.5

Files