@gjsify/tls-native 0.36.0 → 0.37.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/lib/types/index.d.ts +32 -88
  2. package/package.json +10 -10
package/lib/types/index.d.ts CHANGED
@@ -1,24 +1,10 @@
1
- /** Parsed OCSP response from `Tls.parse_ocsp_response`. Mirrors the
2
- * GObject properties exposed by `GjsifyTls.OcspResponseInfo`. */
1
+ /** Parsed OCSP response from `Tls.parse_ocsp_response`. */
3
2
  export interface OcspResponseInfo {
4
- /**
5
- * `responseStatus` per RFC 6960 §4.2.1.
6
- * 0 = successful
7
- * 1 = malformedRequest
8
- * 2 = internalError
9
- * 3 = tryLater
10
- * 5 = sigRequired
11
- * 6 = unauthorized
12
- */
3
+ /** `responseStatus` per RFC 6960 §4.2.1 — see {@link OcspResponseStatus}. */
13
4
  responseStatus: number;
14
5
  /** `producedAt` (Unix seconds, 0 if unparseable). */
15
6
  producedAt: number;
16
- /**
17
- * `certStatus` per RFC 6960 §4.2.1.
18
- * 0 = good
19
- * 1 = revoked
20
- * 2 = unknown
21
- */
7
+ /** `certStatus` per RFC 6960 §4.2.1 — see {@link OcspCertStatus}. */
22
8
  certStatus: number;
23
9
  /** `thisUpdate` (Unix seconds). */
24
10
  thisUpdate: number;
@@ -30,24 +16,14 @@ export interface OcspResponseInfo {
30
16
  * only when certStatus=1. */
31
17
  revocationReason: number;
32
18
  }
33
- /** Native handle returned by `imports.gi.GjsifyTls`. The shape mirrors
34
- * the GIR — `OcspResponseInfo` properties are exposed in camelCase via
35
- * GObject's automatic property accessor lowering on the GJS side. */
19
+ /** Native handle from `imports.gi.GjsifyTls`. `OcspResponseInfo` properties
20
+ * arrive camelCased via GObject's property-accessor lowering in GJS. */
36
21
  export interface NativeTls {
37
- /**
38
- * Parse a DER-encoded OCSP response (RFC 6960). Returns `null` when
39
- * the bytes are not a valid response (init / import errors).
40
- */
22
+ /** Returns `null` when the bytes are not a valid OCSP response. */
41
23
  parse_ocsp_response(bytes: Uint8Array): OcspResponseInfo | null;
42
24
  }
43
- /**
44
- * Symbolic channel-binding type per RFC 5929 / RFC 9266.
45
- *
46
- * Mirrors `GjsifyTls.ChannelBindingType` in the GIR. Values are stable
47
- * across GnuTLS / OpenSSL / Node — the RFCs assign them implicitly via
48
- * the wire-protocol identifier ("tls-unique", "tls-server-end-point",
49
- * "tls-exporter").
50
- */
25
+ /** Channel-binding type per RFC 5929 / RFC 9266; mirrors
26
+ * `GjsifyTls.ChannelBindingType`. */
51
27
  export declare const TlsChannelBindingType: {
52
28
  /** `tls-unique` (RFC 5929 §3) — TLS 1.0–1.2 only. */
53
29
  readonly TLS_UNIQUE: 0;
@@ -58,25 +34,20 @@ export declare const TlsChannelBindingType: {
58
34
  };
59
35
  export type TlsChannelBindingType = (typeof TlsChannelBindingType)[keyof typeof TlsChannelBindingType];
60
36
  /**
61
- * Minimal Gio.TlsConnection shape — typed structurally so this module
62
- * doesn't take a value-level dep on `@girs/gio-2.0` (would force every
63
- * consumer to install the GIR-types package even on Node). Real
64
- * connections come from `@gjsify/tls`'s `TLSSocket._tlsConnection`.
37
+ * Minimal Gio.TlsConnection shape — typed structurally so this module takes no
38
+ * value-level dep on `@girs/gio-2.0`, which would force the GIR-types package
39
+ * on every consumer, Node included. Real connections come from `@gjsify/tls`'s
40
+ * `TLSSocket._tlsConnection`.
65
41
  */
66
42
  export interface TlsConnectionHandle {
67
43
  /** Tag for type-narrowing — present on real Gio.TlsConnection. */
68
44
  __isTlsConnection?: never;
69
45
  }
70
46
  /**
71
- * Native SessionAccess wrapper (Phase 2 POC).
47
+ * Native SessionAccess wrapper, mirroring `GjsifyTls.SessionAccess`.
72
48
  *
73
- * Mirrors `GjsifyTls.SessionAccess` from the GIR. Every method currently
74
- * throws a GLib.Error with domain `gjsify-tls-session-access-error-quark`
75
- * and code `NOT_SUPPORTED` — see `docs/poc/tls-phase2-session-access.md`
76
- * for the open struct-layout question gating the real implementation.
77
- *
78
- * The shape is locked in now so flipping the native side from
79
- * throw → real is a transparent change for JS callers.
49
+ * On a non-GnuTLS GIO TLS backend every method throws a GLib.Error with
50
+ * domain `gjsify-tls-session-access-error-quark`, code `NOT_SUPPORTED`.
80
51
  */
81
52
  export interface NativeSessionAccess {
82
53
  /** `gnutls_session_is_resumed` — true if the session was resumed. */
@@ -96,16 +67,10 @@ export interface NativeSessionAccess {
96
67
  }
97
68
  /** Native `SessionAccess` class constructor surface (GIR static methods). */
98
69
  export interface NativeSessionAccessClass {
99
- /**
100
- * Returns whether the native session access layer is functional.
101
- * Currently always `false` — see `hasTlsSessionAccess()` for the
102
- * preferred predicate that callers should use.
103
- */
70
+ /** True when the GnuTLS session bridge works here; prefer the
71
+ * {@link hasTlsSessionAccess} wrapper, which tolerates a missing typelib. */
104
72
  is_supported(): boolean;
105
- /**
106
- * Build a SessionAccess for a live `Gio.TlsConnection`. Returns
107
- * `null` if @connection is `null`.
108
- */
73
+ /** Returns `null` if @connection is `null`. */
109
74
  for_connection(connection: TlsConnectionHandle | null): NativeSessionAccess | null;
110
75
  }
111
76
  export interface GjsifyTlsModule {
@@ -118,32 +83,21 @@ export declare const nativeTls: GjsifyTlsModule | null;
118
83
  /** Returns `true` when the GjsifyTls native library is available. */
119
84
  export declare function hasNativeTls(): boolean;
120
85
  /**
121
- * Parse a DER-encoded OCSP response (RFC 6960).
122
- *
123
- * Throws when `@gjsify/tls-native`'s typelib is not loaded — callers can
124
- * gate with `hasNativeTls()` and fall back to a pure-JS path (no such path
125
- * exists today; OCSP parsing requires either the GnuTLS bridge here or a
126
- * full RFC 6960 ASN.1 decoder).
86
+ * Parse a DER-encoded OCSPResponse (RFC 6960) — typically the body of a POST to
87
+ * the cert's AIA responder URL. `null` when the bytes do not parse.
127
88
  *
128
- * @param bytes DER-encoded OCSPResponse bytes (typically the body of a
129
- * POST response from the cert's AIA OCSP responder URL).
130
- * @returns Parsed response on success, `null` when the bytes don't
131
- * parse as an OCSPResponse.
89
+ * Throws without the typelib; gate on `hasNativeTls()`. There is no pure-JS
90
+ * fallback — the alternative would be a full RFC 6960 ASN.1 decoder.
132
91
  */
133
92
  export declare function parseOcspResponse(bytes: Uint8Array): OcspResponseInfo | null;
134
- /**
135
- * Symbolic OCSP cert-status values per RFC 6960 §4.2.1. Use as
136
- * `OcspCertStatus.GOOD` for readable comparisons.
137
- */
93
+ /** OCSP cert-status values per RFC 6960 §4.2.1. */
138
94
  export declare const OcspCertStatus: {
139
95
  readonly GOOD: 0;
140
96
  readonly REVOKED: 1;
141
97
  readonly UNKNOWN: 2;
142
98
  };
143
99
  export type OcspCertStatus = (typeof OcspCertStatus)[keyof typeof OcspCertStatus];
144
- /**
145
- * Symbolic OCSP responseStatus values per RFC 6960 §4.2.1.
146
- */
100
+ /** OCSP responseStatus values per RFC 6960 §4.2.1. */
147
101
  export declare const OcspResponseStatus: {
148
102
  readonly SUCCESSFUL: 0;
149
103
  readonly MALFORMED_REQUEST: 1;
@@ -154,27 +108,17 @@ export declare const OcspResponseStatus: {
154
108
  };
155
109
  export type OcspResponseStatus = (typeof OcspResponseStatus)[keyof typeof OcspResponseStatus];
156
110
  /**
157
- * Returns `true` when the Phase 2 session-access bridge is functional.
111
+ * Returns `true` when the session-access bridge works on this host: it needs the
112
+ * typelib AND glib-networking's GnuTLS backend, whose private struct the C shim
113
+ * reads (`docs/poc/tls-phase2-session-access.md`).
158
114
  *
159
- * Today this always returns `false` even when the native typelib is
160
- * loaded — the underlying gnutls_session_t extraction from
161
- * `Gio.TlsConnection` is not yet implemented. See
162
- * `docs/poc/tls-phase2-session-access.md` for the open question.
163
- *
164
- * Callers (e.g. `@gjsify/tls`'s `TLSSocket.getFinished()`) should gate
165
- * with this predicate so consumers can detect "not supported on this
166
- * platform / version" without triggering a thrown error.
167
- *
168
- * When the native side becomes functional this predicate flips to
169
- * `true` automatically (it reads `GjsifyTls.SessionAccess.is_supported()`).
115
+ * Callers such as `@gjsify/tls`'s `TLSSocket.getFinished()` gate on this so an
116
+ * unsupported backend degrades to Node's no-session contract instead of throwing.
170
117
  */
171
118
  export declare function hasTlsSessionAccess(): boolean;
172
119
  /**
173
- * Build a {@link NativeSessionAccess} wrapper around a live
174
- * `Gio.TlsConnection`. Returns `null` if @connection is `null` or
175
- * the native typelib is unavailable.
176
- *
177
- * The returned object's methods THROW until {@link hasTlsSessionAccess}
178
- * starts returning `true` — surface stays stable across the impl flip.
120
+ * Wrap a live `Gio.TlsConnection`. `null` if @connection is `null` or the native
121
+ * typelib is unavailable; the returned methods throw `NOT_SUPPORTED` unless
122
+ * {@link hasTlsSessionAccess} is `true`.
179
123
  */
180
124
  export declare function createSessionAccess(connection: TlsConnectionHandle | null): NativeSessionAccess | null;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gjsify/tls-native",
3
- "version": "0.36.0",
3
+ "version": "0.37.0",
4
4
  "description": "Optional Vala/GObject bridge providing GnuTLS capabilities not exposed by Gio.TlsConnection — OCSP-response parsing (RFC 6960), session resumption data extraction, channel binding (tls-finished bytes for SCRAM-SHA-*). Enhances @gjsify/tls when installed.",
5
5
  "type": "module",
6
6
  "main": "lib/esm/index.js",
@@ -67,8 +67,8 @@
67
67
  "@girs/gobject-2.0": "^4.1.0"
68
68
  },
69
69
  "devDependencies": {
70
- "@gjsify/cli": "^0.36.0",
71
- "@gjsify/unit": "^0.36.0",
70
+ "@gjsify/cli": "^0.37.0",
71
+ "@gjsify/unit": "^0.37.0",
72
72
  "@ts-for-gir/cli": "^4.1.0",
73
73
  "@types/node": "^25.9.2",
74
74
  "typescript": "^6.0.3"
@@ -84,12 +84,12 @@
84
84
  },
85
85
  "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/node/tls-native#readme",
86
86
  "optionalDependencies": {
87
- "@gjsify/tls-native-darwin-arm64": "0.36.0",
88
- "@gjsify/tls-native-darwin-x64": "0.36.0",
89
- "@gjsify/tls-native-linux-arm64": "0.36.0",
90
- "@gjsify/tls-native-linux-ppc64": "0.36.0",
91
- "@gjsify/tls-native-linux-riscv64": "0.36.0",
92
- "@gjsify/tls-native-linux-s390x": "0.36.0",
93
- "@gjsify/tls-native-linux-x64": "0.36.0"
87
+ "@gjsify/tls-native-darwin-arm64": "0.37.0",
88
+ "@gjsify/tls-native-darwin-x64": "0.37.0",
89
+ "@gjsify/tls-native-linux-arm64": "0.37.0",
90
+ "@gjsify/tls-native-linux-ppc64": "0.37.0",
91
+ "@gjsify/tls-native-linux-riscv64": "0.37.0",
92
+ "@gjsify/tls-native-linux-s390x": "0.37.0",
93
+ "@gjsify/tls-native-linux-x64": "0.37.0"
94
94
  }
95
95
  }