fix(cli): restore type narrowing for SSL typed-constant assertions

Convert SslAssertionBuilder.certificate/connection to typed overloads so
property names are narrowed to known unions (typos are compile errors +
autocomplete), and the two typed-constant properties narrow the builder
target type: connection('tlsVersion') -> TlsVersionValue,
certificate('signatureAlgorithm') -> SignatureAlgorithmValue. cipherSuite
stays unconstrained by prior decision.

Add type-level @ts-expect-error coverage proving the narrowing, plus
runtime validation coverage for the removed SSL-only operators
(MATCHES, GREATER_THAN_OR_EQUAL) and the per-property comparison
whitelist (sans/serialNumber/ocspStatus rejects; sans/resolvedIp accepts).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013AYwkvoaANQTH5dGStbBj2

Author: danielpaulus

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

@@ -112,4 +112,38 @@ describe('SslAssertionBuilder', () => {
       })
     })
   })
+
+  // These cases assert compile-time narrowing. The `@ts-expect-error` lines are the
+  // real assertions: `tsc --build` fails if any becomes a false positive (an unused
+  // expect-error). The runtime `expect` keeps the block a valid test.
+  describe('type narrowing (compile-time)', () => {
+    it('constrains connection(tlsVersion) targets to TlsVersionValue', () => {
+      expect(SslAssertionBuilder.connection('tlsVersion').equals(TlsVersion.TLS1_3)).toMatchObject({
+        source: 'CONNECTION', property: 'tlsVersion', comparison: 'EQUALS', target: 'TLS1.3',
+      })
+      // @ts-expect-error 'bogus' is not a TlsVersionValue
+      SslAssertionBuilder.connection('tlsVersion').equals('bogus')
+    })
+
+    it('constrains certificate(signatureAlgorithm) targets to SignatureAlgorithmValue', () => {
+      expect(SslAssertionBuilder.certificate('signatureAlgorithm').equals(SignatureAlgorithm.SHA256_RSA)).toMatchObject({
+        source: 'CERTIFICATE', property: 'signatureAlgorithm', comparison: 'EQUALS', target: 'SHA256-RSA',
+      })
+      // @ts-expect-error 'nope' is not a SignatureAlgorithmValue
+      SslAssertionBuilder.certificate('signatureAlgorithm').equals('nope')
+    })
+
+    it('rejects unknown property names', () => {
+      // @ts-expect-error 'bogusProperty' is not a CertificateProperty
+      SslAssertionBuilder.certificate('bogusProperty')
+      // @ts-expect-error 'bogusProperty' is not a ConnectionProperty
+      SslAssertionBuilder.connection('bogusProperty')
+    })
+
+    it('leaves cipherSuite targets unconstrained (arbitrary string)', () => {
+      expect(SslAssertionBuilder.connection('cipherSuite').equals('SOME_FUTURE_SUITE')).toMatchObject({
+        source: 'CONNECTION', property: 'cipherSuite', comparison: 'EQUALS', target: 'SOME_FUTURE_SUITE',
+      })
+    })
+  })
 })

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

@@ -352,6 +352,67 @@ describe('SslMonitor', () => {
       ]))
     })
 
+    it('should error on removed SSL-only operators against the new grammar', async () => {
+      // The regex (MATCHES) and >= (GREATER_THAN_OR_EQUAL) operators were dropped for SSL;
+      // they must be rejected on every source that could plausibly carry them.
+      const cases: Array<{ assertion: SslRequest['assertions'][number]; message: string }> = [
+        {
+          assertion: { source: 'CERTIFICATE', property: 'signatureAlgorithm', comparison: 'MATCHES', target: 'x', regex: null },
+          message: 'The CERTIFICATE "signatureAlgorithm" assertion at "request.assertions[0]" has an unsupported comparison "MATCHES".',
+        },
+        {
+          assertion: { source: 'CONNECTION', property: 'tlsVersion', comparison: 'GREATER_THAN_OR_EQUAL', target: 'TLS1.2', regex: null },
+          message: 'The CONNECTION "tlsVersion" assertion at "request.assertions[0]" has an unsupported comparison "GREATER_THAN_OR_EQUAL".',
+        },
+        {
+          assertion: { source: 'RESPONSE_TIME', property: '', comparison: 'GREATER_THAN_OR_EQUAL', target: '100', regex: null },
+          message: 'The RESPONSE_TIME assertion at "request.assertions[0]" has an unsupported comparison "GREATER_THAN_OR_EQUAL".',
+        },
+      ]
+      for (const { assertion, message } of cases) {
+        const diags = await validateWith([assertion])
+        expect(diags.isFatal()).toEqual(true)
+        expect(diags.observations).toEqual(expect.arrayContaining([
+          expect.objectContaining({ message: expect.stringContaining(message) }),
+        ]))
+      }
+    })
+
+    it('should enforce the per-property comparison whitelist', async () => {
+      const cases: Array<{ assertion: SslRequest['assertions'][number]; message: string }> = [
+        {
+          // sans is STRING_LIST — only CONTAINS / NOT_CONTAINS, so EQUALS is rejected.
+          assertion: { source: 'CERTIFICATE', property: 'sans', comparison: 'EQUALS', target: 'example.com', regex: null },
+          message: 'The CERTIFICATE "sans" assertion at "request.assertions[0]" has an unsupported comparison "EQUALS".',
+        },
+        {
+          // serialNumber is ID — only EQUALS / NOT_EQUALS, so CONTAINS is rejected.
+          assertion: { source: 'CERTIFICATE', property: 'serialNumber', comparison: 'CONTAINS', target: 'ab', regex: null },
+          message: 'The CERTIFICATE "serialNumber" assertion at "request.assertions[0]" has an unsupported comparison "CONTAINS".',
+        },
+        {
+          // ocspStatus is ENUM — only EQUALS / NOT_EQUALS, so CONTAINS is rejected.
+          assertion: { source: 'CONNECTION', property: 'ocspStatus', comparison: 'CONTAINS', target: 'good', regex: null },
+          message: 'The CONNECTION "ocspStatus" assertion at "request.assertions[0]" has an unsupported comparison "CONTAINS".',
+        },
+      ]
+      for (const { assertion, message } of cases) {
+        const diags = await validateWith([assertion])
+        expect(diags.isFatal()).toEqual(true)
+        expect(diags.observations).toEqual(expect.arrayContaining([
+          expect.objectContaining({ message: expect.stringContaining(message) }),
+        ]))
+      }
+    })
+
+    it('should accept the list-oriented comparisons the whitelist allows', async () => {
+      const diags = await validateWith([
+        { source: 'CERTIFICATE', property: 'sans', comparison: 'CONTAINS', target: 'example.com', regex: null },
+        { source: 'CONNECTION', property: 'resolvedIp', comparison: 'NOT_CONTAINS', target: '10.0.0.1', regex: null },
+      ])
+      expect(diags.isFatal()).toEqual(false)
+    })
+
     it('should not error on assertions built with SslAssertionBuilder', async () => {
       const diags = await validateWith([
         SslAssertionBuilder.certificate('daysUntilExpiry').greaterThan(30),

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

@@ -104,6 +104,33 @@ type SslAssertionSource =
 
 export type SslAssertion = CoreAssertion<SslAssertionSource>
 
+// The certificate/connection property names the backend understands. Narrowing the
+// `property` parameter to these unions turns a typo into a compile error and drives
+// autocomplete. The runtime whitelist in ssl-assertion-validation.ts is the source of
+// truth for object-literal assertions that bypass the builder.
+type CertificateProperty =
+  | 'daysUntilExpiry'
+  | 'subjectCN'
+  | 'issuerCN'
+  | 'serialNumber'
+  | 'fingerprintSha256'
+  | 'issuerFingerprintSha256'
+  | 'keySizeBits'
+  | 'keyAlgorithm'
+  | 'signatureAlgorithm'
+  | 'sans'
+  | 'selfSigned'
+  | 'isCA'
+
+type ConnectionProperty =
+  | 'tlsVersion'
+  | 'cipherSuite'
+  | 'hostnameVerified'
+  | 'chainTrusted'
+  | 'ocspStapled'
+  | 'ocspStatus'
+  | 'resolvedIp'
+
 /**
  * Builder class for creating SSL monitor assertions.
  *
@@ -137,7 +164,9 @@ export class SslAssertionBuilder {
    * @param property The certificate property to assert on (e.g. `'daysUntilExpiry'`,
    *   `'issuerCN'`, `'signatureAlgorithm'`, `'sans'`, `'selfSigned'`).
    */
-  static certificate (property: string) {
+  static certificate (property: 'signatureAlgorithm'): GeneralAssertionBuilder<SslAssertionSource, SignatureAlgorithmValue>
+  static certificate (property: CertificateProperty): GeneralAssertionBuilder<SslAssertionSource>
+  static certificate (property: CertificateProperty) {
     return new GeneralAssertionBuilder<SslAssertionSource>('CERTIFICATE', property)
   }
 
@@ -146,7 +175,9 @@ export class SslAssertionBuilder {
    * @param property The connection property to assert on (e.g. `'tlsVersion'`,
    *   `'cipherSuite'`, `'hostnameVerified'`, `'ocspStatus'`, `'resolvedIp'`).
    */
-  static connection (property: string) {
+  static connection (property: 'tlsVersion'): GeneralAssertionBuilder<SslAssertionSource, TlsVersionValue>
+  static connection (property: ConnectionProperty): GeneralAssertionBuilder<SslAssertionSource>
+  static connection (property: ConnectionProperty) {
     return new GeneralAssertionBuilder<SslAssertionSource>('CONNECTION', property)
   }