feat(ssl-assertion): export TlsVersion, CipherSuite, SignatureAlgorithm typed constants (#1392)

* feat(reporters): per-type TRACEROUTE/GRPC/SSL result rendering (P4-CLI-RESULTS)

Render failure-debug diagnostics for the three uptime monitor types across
every CLI result surface, mirroring the 4.1 public check-results fields:

- rest/check-results.ts: typed TracerouteCheckResult/GrpcCheckResult/
  SslCheckResult interfaces + additive fields on CheckResult/CheckResultField.
- formatters/check-result-detail.ts: per-type terminal + markdown diagnostic
  block (checks results get) keyed on the typed fields.
- reporters/util.ts: GRPC/SSL/TRACEROUTE branches in formatCheckResult
  (checkly test terminal), sourced from the runner artifact (checkRunData).
- formatters/batch-stats.ts: add the three types to TIMING_TYPES.
- reporters/json.ts: emit a per-type diagnostics object in the JSON report
  for a failed run (checkly test --reporter json).

Snapshot + assertion tests for each type across all three surfaces.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(constructs): add GrpcMonitor, SslMonitor, TracerouteMonitor IaC constructs

Implement the missing CLI constructs so users can author and deploy gRPC, SSL
and Traceroute uptime monitors via checkly/constructs, and so backend CLI export
templates that import these classes compile.

Constructs follow the DNS/TCP/ICMP monitor pattern (extend Monitor, register
with Session, validate, synthesize):

- GrpcMonitor / GrpcRequest / GrpcConfig / GrpcMetadata + GrpcAssertionBuilder
  (RESPONSE_TIME, GRPC_STATUS_CODE, GRPC_HEALTHCHECK_STATUS, GRPC_RESPONSE,
  GRPC_METADATA). checkType GRPC, top-level degraded/maxResponseTime (<=30000).
- SslMonitor / SslRequest / SslConfig / SecurityBaseline + SslAssertionBuilder
  (cert expiry, chain, hostname, TLS version, cipher, key size, etc). checkType
  SSL; response-time limits live in sslConfig (degraded/maxResponseTimeMs).
- TracerouteMonitor / TracerouteRequest + TracerouteAssertionBuilder
  (RESPONSE_TIME, HOP_COUNT, PACKET_LOSS). checkType TRACEROUTE, top-level
  degraded/maxResponseTime (<=30000); port dropped for ICMP probes.

Request shapes mirror the public API (verified against checkly-go-sdk types and
the p5-parity captured payloads). Wires exports in constructs/index.ts, import
codegen in check-codegen.ts (GRPC/SSL/TRACEROUTE -> *MonitorCodegen), and adds
the three types to constants.CheckTypes.

Tests: construct synthesize/validation/grouping specs, codegen specs (incl.
ICMP port-strip and assertion builders), and a regression spec asserting the
backend-style export snippets compile against checkly/constructs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(deploy): skip code-bundle upload when nothing was bundled

archive.store() (the 'Uploading Playwright tests' step) was called
unconditionally on every deploy. For a project of only uptime monitors
(GRPC/SSL/TRACEROUTE), the bundler registers no files, so this uploaded an
empty Playwright bundle — an unnecessary code-bundle upload in production, and
a hard failure in devenv where it 500s on the storage backend.

The remote code bundle is consumed only by Playwright check suites (via
bundler.marker -> playwright-check.ts); browser checks upload snapshots
separately. Add Bundler.isEmpty and skip store() when no files were registered.

Refs T65.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(cli): wire gRPC/SSL/Traceroute analytics paths + connection-error rendering

Addresses review (Simo) new-monitor checklist gaps:
- src/rest/analytics.ts: add checkTypeToPath (grpc-checks/ssl/traceroute) and
  defaultMetrics for the three types, matching the backend analytics routes +
  metric registries (gRPC total_*, SSL handshakeTimeMs_*/daysUntilExpiry_avg,
  TRACEROUTE finalHopLatencyAvg_*/totalHops_avg).
- src/reporters/util.ts: add the Connection Error subsection to the GRPC/SSL/
  TRACEROUTE result blocks, mirroring ICMP/DNS.

* docs(cli): AI context references + examples for gRPC/SSL/Traceroute monitors

Addresses review (Simo) new-monitor checklist Phases 5 & 7:
- ai-context/references/configure-{grpc,ssl,traceroute}-monitors.md + REFERENCES
  and EXAMPLE_CONFIGS entries in context.ts (inline exampleConfig).
- examples/advanced-project{,-js}/src/__checks__/uptime/{grpc,ssl,traceroute}
  TS + JS examples with group, assertions, and doc-link comments.

* test(cli): e2e deploy fixtures + Create assertions for gRPC/SSL/Traceroute

Addresses review (Simo) new-monitor checklist Phase 6:
- e2e/__tests__/fixtures/deploy-project/{grpc,ssl,traceroute}.check.ts (activated:false)
- deploy.spec.ts: assert the three logical IDs in the Create output.

* feat(cli): support TEXT_BODY assertions for gRPC monitors

Mirror monorepo #2730 which added TEXT_BODY to grpcMonitorAssertionSources.
Adds GrpcAssertionBuilder.textBody() (source TEXT_BODY) + codegen case,
matching the API check's textBody() builder.

* refactor(cli): restructure SslMonitor props per review (wire shape unchanged)

Per @sorccu's review: make SslMonitor ergonomics consistent with other monitors.
- degradedResponseTime/maxResponseTime -> construct top level (were in sslConfig)
- hostname/port/ipFamily -> request top level (were in sslConfig)
- sslClientCertificateId -> into sslConfig (was on request)
synthesize() remaps to the identical API wire shape (request.sslConfig.* +
request.sslClientCertificateId), so the payload the backend receives is unchanged.
Updated codegen (wire->construct), unit + codegen + export-snippet tests,
examples (ts+js), e2e fixture, and AI context.

* refactor(cli): drop Ms suffix on SslConfig.handshakeTimeout per review

@sorccu: we don't suffix timeout properties with Ms even when the value is
milliseconds. Renames the construct field handshakeTimeoutMs -> handshakeTimeout;
synthesize() and the codegen wire interface keep the API's handshakeTimeoutMs.

* refactor(cli): emit SSL degraded/maxResponseTime at top level to match gRPC/traceroute wire

* feat(ssl-assertion): export TlsVersion, CipherSuite, SignatureAlgorithm typed constants

Add three exported const objects and matching type aliases so callers get
IDE autocomplete for the finite value sets:
- TlsVersion: TLS1_0/TLS1_1/TLS1_2/TLS1_3
- SignatureAlgorithm: common X.509 algorithm strings (sha256WithRSAEncryption, etc.)
- CipherSuite: TLS 1.3 suites + widely-deployed TLS 1.2 ECDHE/RSA suites

The GeneralAssertionBuilder API is unchanged; existing string-literal calls
continue to compile and work at runtime.

* fix(ssl-assertion): real type safety + correct SignatureAlgorithm wire values

Blocker 1 — GeneralAssertionBuilder now takes an optional TargetType generic
parameter (default: string|number|boolean for full backward compatibility).
tlsVersion(), cipherSuite(), signatureAlgorithm() return the narrowed form so
.equals() only accepts the typed union — invalid values are rejected at compile
time. matches() stays string (it carries a regex, not a value to compare).

Blocker 2 — SignatureAlgorithm constants now use Go's
x509.Certificate.SignatureAlgorithm.String() output (SHA256-RSA, ECDSA-SHA256,
etc.) matching the values the runner evaluates assertions against.

New test file ssl-assertion.spec.ts uses @ts-expect-error to prove:
- valid constants / string literals are accepted for all three typed builders
- invalid strings (wrong format, arbitrary strings, numeric) are rejected
- matches() remains unconstrained as intended

* fix(ssl-assertion): revert cipherSuite to unconstrained; complete SignatureAlgorithm union

cipherSuite() — Go's tls.CipherSuiteName() returns hundreds of IANA names plus
0x.... hex fallbacks; the 15-value union blocked valid values like
TLS_RSA_WITH_RC4_128_SHA. Reverted the builder to unconstrained string. The
CipherSuite constants remain for autocomplete convenience.

SignatureAlgorithm — completed the union to the full Go x509.SignatureAlgorithm.String()
set (16 values): added MD2-RSA, MD5-RSA, DSA-SHA1, DSA-SHA256, ECDSA-SHA1.
The type now covers every value the runner can emit without blocking any valid input.

Updated ssl-assertion.spec.ts: removed @ts-expect-error for cipher strings (now
unconstrained), added tests showing arbitrary cipher suite strings compile, and
expanded the signatureAlgorithm test to cover all 16 constants.

* refactor(cli): drop greaterThanOrEqual and matches from SSL assertions [SIM-295]

Remove the GREATER_THAN_OR_EQUAL (`greaterThanOrEqual`) and MATCHES (`matches`)
comparison operators from the CLI assertion builders — we are not yet sure we
want to keep these assertions. Drops the two methods from the shared
Numeric/General assertion builders, the two members from the Comparison union,
and the related SSL examples/docs/tests. `tlsVersion`, `keySizeBits`,
`cipherSuite` and `signatureAlgorithm` keep `equals`/`notEquals`, which remain
backend-valid.

The backend (Joi §9 + go-runner) still supports both operators, so this only
removes the CLI surface and they can be re-exposed later if we decide to keep
them.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NC9pESYE5wGqy5TKRzufyc

---------

Co-authored-by: Ubuntu <ubuntu@ip-172-31-7-108.eu-central-1.compute.internal>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

packages/cli/src/constructs/__tests__/ssl-assertion.spec.ts

@@ -0,0 +1,101 @@
+/**
+ * Type-level tests for SslAssertionBuilder typed constants.
+ *
+ * These tests verify two things:
+ * 1. Valid constant / string-literal values are accepted by the typed builders.
+ * 2. Invalid strings are REJECTED at compile time (via @ts-expect-error) where
+ *    the builder is strictly typed.
+ *
+ * If a @ts-expect-error directive becomes "unused" it means the underlying typing
+ * was loosened — investigate before removing it.
+ */
+
+import { describe, it, expect } from 'vitest'
+import {
+  SslAssertionBuilder,
+  TlsVersion,
+  CipherSuite,
+  SignatureAlgorithm,
+} from '../index.js'
+
+describe('SslAssertionBuilder — typed target values', () => {
+  describe('tlsVersion() — strict 4-value union', () => {
+    it('accepts all TlsVersion constants', () => {
+      expect(SslAssertionBuilder.tlsVersion().equals(TlsVersion.TLS1_0)).toBeTruthy()
+      expect(SslAssertionBuilder.tlsVersion().equals(TlsVersion.TLS1_1)).toBeTruthy()
+      expect(SslAssertionBuilder.tlsVersion().equals(TlsVersion.TLS1_2)).toBeTruthy()
+      expect(SslAssertionBuilder.tlsVersion().equals(TlsVersion.TLS1_3)).toBeTruthy()
+    })
+
+    it('accepts TLS version string literals directly', () => {
+      expect(SslAssertionBuilder.tlsVersion().equals('TLS1.2')).toBeTruthy()
+      expect(SslAssertionBuilder.tlsVersion().equals('TLS1.3')).toBeTruthy()
+    })
+
+    it('rejects an arbitrary string that is not a valid TLS version', () => {
+      // @ts-expect-error 'not-a-tls-version' is not assignable to TlsVersionValue
+      SslAssertionBuilder.tlsVersion().equals('not-a-tls-version')
+    })
+
+    it('rejects a numeric TLS version (wrong type)', () => {
+      // @ts-expect-error number is not assignable to TlsVersionValue
+      SslAssertionBuilder.tlsVersion().equals(1.3)
+    })
+  })
+
+  describe('signatureAlgorithm() — complete Go x509.SignatureAlgorithm.String() union', () => {
+    it('accepts all SignatureAlgorithm constants (Go format)', () => {
+      // RSA family
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.MD2_RSA)).toBeTruthy()
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.MD5_RSA)).toBeTruthy()
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.SHA1_RSA)).toBeTruthy()
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.SHA256_RSA)).toBeTruthy()
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.SHA384_RSA)).toBeTruthy()
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.SHA512_RSA)).toBeTruthy()
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.SHA256_RSAPSS)).toBeTruthy()
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.SHA384_RSAPSS)).toBeTruthy()
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.SHA512_RSAPSS)).toBeTruthy()
+      // DSA family
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.DSA_SHA1)).toBeTruthy()
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.DSA_SHA256)).toBeTruthy()
+      // ECDSA family
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.ECDSA_SHA1)).toBeTruthy()
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.ECDSA_SHA256)).toBeTruthy()
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.ECDSA_SHA384)).toBeTruthy()
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.ECDSA_SHA512)).toBeTruthy()
+      // EdDSA
+      expect(SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.ED25519)).toBeTruthy()
+    })
+
+    it('accepts Go-format string literals directly', () => {
+      expect(SslAssertionBuilder.signatureAlgorithm().equals('SHA256-RSA')).toBeTruthy()
+      expect(SslAssertionBuilder.signatureAlgorithm().equals('ECDSA-SHA256')).toBeTruthy()
+      expect(SslAssertionBuilder.signatureAlgorithm().equals('Ed25519')).toBeTruthy()
+    })
+
+    it('rejects OID-style strings (wrong format — the runner uses Go String() not OID names)', () => {
+      // @ts-expect-error 'sha256WithRSAEncryption' is not assignable to SignatureAlgorithmValue
+      SslAssertionBuilder.signatureAlgorithm().equals('sha256WithRSAEncryption')
+    })
+
+    it('rejects arbitrary strings', () => {
+      // @ts-expect-error 'invalid-alg' is not assignable to SignatureAlgorithmValue
+      SslAssertionBuilder.signatureAlgorithm().equals('invalid-alg')
+    })
+  })
+
+  describe('cipherSuite() — intentionally unconstrained (open-ended IANA set)', () => {
+    it('accepts CipherSuite constants for common suites', () => {
+      expect(SslAssertionBuilder.cipherSuite().equals(CipherSuite.TLS_AES_256_GCM_SHA384)).toBeTruthy()
+      expect(SslAssertionBuilder.cipherSuite().equals(CipherSuite.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256)).toBeTruthy()
+    })
+
+    it('accepts any string — including suites not in the CipherSuite constant list', () => {
+      // These are valid Go tls.CipherSuiteName() outputs that exceed the short constant list
+      expect(SslAssertionBuilder.cipherSuite().equals('TLS_RSA_WITH_RC4_128_SHA')).toBeTruthy()
+      expect(SslAssertionBuilder.cipherSuite().equals('TLS_RSA_WITH_3DES_EDE_CBC_SHA')).toBeTruthy()
+      expect(SslAssertionBuilder.cipherSuite().notEquals('TLS_RSA_WITH_RC4_128_SHA')).toBeTruthy()
+      expect(SslAssertionBuilder.cipherSuite().equals('TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256')).toBeTruthy()
+    })
+  })
+})

packages/cli/src/constructs/internal/assertion.ts

@@ -59,7 +59,19 @@ export class NumericAssertionBuilder<Source extends string, Property extends str
   }
 }
 
-export class GeneralAssertionBuilder<Source extends string> {
+/**
+ * General assertion builder supporting string / number / boolean targets.
+ *
+ * The optional `TargetType` parameter narrows the value-comparison methods
+ * (`equals`, `notEquals`, `lessThan`, `greaterThan`)
+ * to a specific set of values — e.g. `TlsVersionValue` for TLS version
+ * assertions. When omitted it defaults to `string | number | boolean`,
+ * preserving full backward compatibility.
+ */
+export class GeneralAssertionBuilder<
+  Source extends string,
+  TargetType extends string | number | boolean = string | number | boolean,
+> {
   source: Source
   property?: string
   regex?: string
@@ -70,11 +82,11 @@ export class GeneralAssertionBuilder<Source extends string> {
     this.regex = regex
   }
 
-  equals (target: string | number | boolean): Assertion<Source> {
+  equals (target: TargetType): Assertion<Source> {
     return this._toAssertion('EQUALS', target)
   }
 
-  notEquals (target: string | number | boolean): Assertion<Source> {
+  notEquals (target: TargetType): Assertion<Source> {
     return this._toAssertion('NOT_EQUALS', target)
   }
 
@@ -86,11 +98,11 @@ export class GeneralAssertionBuilder<Source extends string> {
     return this._toAssertion('NOT_HAS_KEY', target)
   }
 
-  hasValue (target: string | number | boolean): Assertion<Source> {
+  hasValue (target: TargetType): Assertion<Source> {
     return this._toAssertion('HAS_VALUE', target)
   }
 
-  notHasValue (target: string | number | boolean): Assertion<Source> {
+  notHasValue (target: TargetType): Assertion<Source> {
     return this._toAssertion('NOT_HAS_VALUE', target)
   }
 
@@ -102,11 +114,11 @@ export class GeneralAssertionBuilder<Source extends string> {
     return this._toAssertion('NOT_EMPTY')
   }
 
-  lessThan (target: string | number | boolean): Assertion<Source> {
+  lessThan (target: TargetType): Assertion<Source> {
     return this._toAssertion('LESS_THAN', target)
   }
 
-  greaterThan (target: string | number | boolean): Assertion<Source> {
+  greaterThan (target: TargetType): Assertion<Source> {
     return this._toAssertion('GREATER_THAN', target)
   }
 

packages/cli/src/constructs/ssl-assertion.ts

@@ -1,5 +1,91 @@
 import { Assertion as CoreAssertion, NumericAssertionBuilder, GeneralAssertionBuilder } from './internal/assertion.js'
 
+/**
+ * Known TLS protocol versions for use with {@link SslAssertionBuilder.tlsVersion}.
+ *
+ * @example
+ * ```typescript
+ * SslAssertionBuilder.tlsVersion().equals(TlsVersion.TLS1_3)
+ * ```
+ */
+export const TlsVersion = {
+  TLS1_0: 'TLS1.0',
+  TLS1_1: 'TLS1.1',
+  TLS1_2: 'TLS1.2',
+  TLS1_3: 'TLS1.3',
+} as const
+
+export type TlsVersionValue = (typeof TlsVersion)[keyof typeof TlsVersion]
+
+/**
+ * Signature algorithms as reported by Go's `x509.Certificate.SignatureAlgorithm.String()`.
+ * These are the exact values the SSL runner evaluates assertions against — use these
+ * constants (or the string literals they represent) with {@link SslAssertionBuilder.signatureAlgorithm}.
+ *
+ * @example
+ * ```typescript
+ * SslAssertionBuilder.signatureAlgorithm().equals(SignatureAlgorithm.SHA256_RSA)
+ * ```
+ */
+export const SignatureAlgorithm = {
+  // RSA
+  MD2_RSA: 'MD2-RSA',
+  MD5_RSA: 'MD5-RSA',
+  SHA1_RSA: 'SHA1-RSA',
+  SHA256_RSA: 'SHA256-RSA',
+  SHA384_RSA: 'SHA384-RSA',
+  SHA512_RSA: 'SHA512-RSA',
+  SHA256_RSAPSS: 'SHA256-RSAPSS',
+  SHA384_RSAPSS: 'SHA384-RSAPSS',
+  SHA512_RSAPSS: 'SHA512-RSAPSS',
+  // DSA
+  DSA_SHA1: 'DSA-SHA1',
+  DSA_SHA256: 'DSA-SHA256',
+  // ECDSA
+  ECDSA_SHA1: 'ECDSA-SHA1',
+  ECDSA_SHA256: 'ECDSA-SHA256',
+  ECDSA_SHA384: 'ECDSA-SHA384',
+  ECDSA_SHA512: 'ECDSA-SHA512',
+  // EdDSA
+  ED25519: 'Ed25519',
+} as const
+
+export type SignatureAlgorithmValue = (typeof SignatureAlgorithm)[keyof typeof SignatureAlgorithm]
+
+/**
+ * Commonly-used IANA cipher suite names for use with
+ * {@link SslAssertionBuilder.cipherSuite}. Includes TLS 1.3 suites and
+ * widely-deployed TLS 1.2 suites.
+ *
+ * @example
+ * ```typescript
+ * SslAssertionBuilder.cipherSuite().equals(CipherSuite.TLS_AES_256_GCM_SHA384)
+ * SslAssertionBuilder.cipherSuite().equals(CipherSuite.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256)
+ * ```
+ */
+export const CipherSuite = {
+  // TLS 1.3
+  TLS_AES_128_GCM_SHA256: 'TLS_AES_128_GCM_SHA256',
+  TLS_AES_256_GCM_SHA384: 'TLS_AES_256_GCM_SHA384',
+  TLS_CHACHA20_POLY1305_SHA256: 'TLS_CHACHA20_POLY1305_SHA256',
+  // TLS 1.2 — ECDHE (forward-secret, preferred)
+  TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256: 'TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256',
+  TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384: 'TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384',
+  TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256: 'TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256',
+  TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384: 'TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384',
+  TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256: 'TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256',
+  TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256: 'TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256',
+  // TLS 1.2 — RSA key exchange
+  TLS_RSA_WITH_AES_128_GCM_SHA256: 'TLS_RSA_WITH_AES_128_GCM_SHA256',
+  TLS_RSA_WITH_AES_256_GCM_SHA384: 'TLS_RSA_WITH_AES_256_GCM_SHA384',
+  TLS_RSA_WITH_AES_128_CBC_SHA256: 'TLS_RSA_WITH_AES_128_CBC_SHA256',
+  TLS_RSA_WITH_AES_256_CBC_SHA256: 'TLS_RSA_WITH_AES_256_CBC_SHA256',
+  TLS_RSA_WITH_AES_128_CBC_SHA: 'TLS_RSA_WITH_AES_128_CBC_SHA',
+  TLS_RSA_WITH_AES_256_CBC_SHA: 'TLS_RSA_WITH_AES_256_CBC_SHA',
+} as const
+
+export type CipherSuiteValue = (typeof CipherSuite)[keyof typeof CipherSuite]
+
 type SslAssertionSource =
   | 'CERT_EXPIRES_IN_DAYS'
   | 'CERT_NOT_EXPIRED'
@@ -12,6 +98,7 @@ type SslAssertionSource =
   | 'ISSUER_FINGERPRINT_SHA256'
   | 'KEY_SIZE_BITS'
   | 'SIGNATURE_ALGORITHM'
+  | 'OCSP_STAPLED'
 
 export type SslAssertion = CoreAssertion<SslAssertionSource>
 
@@ -77,17 +164,24 @@ export class SslAssertionBuilder {
 
   /**
    * Creates an assertion builder for the negotiated TLS version.
-   * @returns A general assertion builder for the TLS version.
+   * The `.equals()` method accepts only the
+   * known TLS version strings — use the {@link TlsVersion} constants or
+   * the string literals `'TLS1.0'`…`'TLS1.3'`.
+   * @returns A typed assertion builder for the TLS version.
    */
-  static tlsVersion () {
-    return new GeneralAssertionBuilder<SslAssertionSource>('TLS_VERSION')
+  static tlsVersion (): GeneralAssertionBuilder<SslAssertionSource, TlsVersionValue> {
+    return new GeneralAssertionBuilder<SslAssertionSource, TlsVersionValue>('TLS_VERSION')
   }
 
   /**
    * Creates an assertion builder for the negotiated cipher suite.
-   * @returns A general assertion builder for the cipher suite.
+   * Go's `tls.CipherSuiteName()` can return hundreds of IANA names plus
+   * `0x....` hex fallbacks, so this builder is intentionally unconstrained.
+   * Use the {@link CipherSuite} constants for common suites (autocomplete),
+   * or pass any string literal / regex pattern as needed.
+   * @returns An unconstrained assertion builder for the cipher suite.
    */
-  static cipherSuite () {
+  static cipherSuite (): GeneralAssertionBuilder<SslAssertionSource> {
     return new GeneralAssertionBuilder<SslAssertionSource>('CIPHER_SUITE')
   }
 
@@ -117,9 +211,21 @@ export class SslAssertionBuilder {
 
   /**
    * Creates an assertion builder for the certificate signature algorithm.
-   * @returns A general assertion builder for the signature algorithm.
+   * Values are Go's `x509.Certificate.SignatureAlgorithm.String()` output
+   * (e.g. `'SHA256-RSA'`, `'ECDSA-SHA256'`). Use the {@link SignatureAlgorithm}
+   * constants or those string literals with `.equals()`.
+   * @returns A typed assertion builder for the signature algorithm.
+   */
+  static signatureAlgorithm (): GeneralAssertionBuilder<SslAssertionSource, SignatureAlgorithmValue> {
+    return new GeneralAssertionBuilder<SslAssertionSource, SignatureAlgorithmValue>('SIGNATURE_ALGORITHM')
+  }
+
+  /**
+   * Creates an assertion builder for whether a stapled OCSP response was
+   * provided during the handshake.
+   * @returns A general assertion builder for the OCSP-stapled status.
    */
-  static signatureAlgorithm () {
-    return new GeneralAssertionBuilder<SslAssertionSource>('SIGNATURE_ALGORITHM')
+  static ocspStapled () {
+    return new GeneralAssertionBuilder<SslAssertionSource>('OCSP_STAPLED')
   }
 }