@gjsify/tls-native 0.4.20

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/index.gjs.spec.js

@@ -0,0 +1 @@
+import{__name as e}from"./_virtual/_rolldown/runtime.js";import{OcspCertStatus as t,OcspResponseStatus as n,hasNativeTls as r,nativeTls as i,parseOcspResponse as a}from"./index.js";import{describe as o,expect as s,it as c,on as l}from"@gjsify/unit";var u=e(async()=>{await l(`Gjs`,async()=>{await o(`@gjsify/tls-native — module loading`,async()=>{await c(`loads the GjsifyTls typelib successfully`,()=>{s(r()).toBe(!0),s(i).not.toBeNull(),s(typeof i?.Tls.parse_ocsp_response).toBe(`function`)})}),await o(`@gjsify/tls-native — parse_ocsp_response`,async()=>{await c(`returns null for empty input`,()=>{s(a(new Uint8Array)).toBeNull()}),await c(`returns null for non-OCSP garbage bytes`,()=>{s(a(new Uint8Array([255,255,255,255,1,2,3]))).toBeNull()}),await c(`returns null for truncated DER (sequence header only)`,()=>{s(a(new Uint8Array([48,1,0]))).toBeNull()})}),await o(`@gjsify/tls-native — symbolic constants`,async()=>{await c(`exposes OcspCertStatus enum-style constants`,()=>{s(t.GOOD).toBe(0),s(t.REVOKED).toBe(1),s(t.UNKNOWN).toBe(2)}),await c(`exposes OcspResponseStatus enum-style constants`,()=>{s(n.SUCCESSFUL).toBe(0),s(n.MALFORMED_REQUEST).toBe(1),s(n.INTERNAL_ERROR).toBe(2),s(n.TRY_LATER).toBe(3),s(n.SIG_REQUIRED).toBe(5),s(n.UNAUTHORIZED).toBe(6)})})})},`default`);export{u as default};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";let e=null;const t=globalThis.imports?.gi;if(t)try{e=t.GjsifyTls}catch{}const n=e;function hasNativeTls(){return e!==null}function parseOcspResponse(t){if(!e)throw Error(`@gjsify/tls-native: native typelib not loaded. Check hasNativeTls() first.`);return e.Tls.parse_ocsp_response(t)}const r={GOOD:0,REVOKED:1,UNKNOWN:2},i={SUCCESSFUL:0,MALFORMED_REQUEST:1,INTERNAL_ERROR:2,TRY_LATER:3,SIG_REQUIRED:5,UNAUTHORIZED:6};export{r as OcspCertStatus,i as OcspResponseStatus,hasNativeTls,n as nativeTls,parseOcspResponse};

package/lib/types/index.d.ts

@@ -0,0 +1,85 @@
+/** Parsed OCSP response from `Tls.parse_ocsp_response`. Mirrors the
+ *  GObject properties exposed by `GjsifyTls.OcspResponseInfo`. */
+export interface OcspResponseInfo {
+    /**
+     * `responseStatus` per RFC 6960 §4.2.1.
+     *   0 = successful
+     *   1 = malformedRequest
+     *   2 = internalError
+     *   3 = tryLater
+     *   5 = sigRequired
+     *   6 = unauthorized
+     */
+    responseStatus: number;
+    /** `producedAt` (Unix seconds, 0 if unparseable). */
+    producedAt: number;
+    /**
+     * `certStatus` per RFC 6960 §4.2.1.
+     *   0 = good
+     *   1 = revoked
+     *   2 = unknown
+     */
+    certStatus: number;
+    /** `thisUpdate` (Unix seconds). */
+    thisUpdate: number;
+    /** `nextUpdate` (Unix seconds, 0 if absent). */
+    nextUpdate: number;
+    /** `revocationTime` (Unix seconds, only meaningful when certStatus=1). */
+    revocationTime: number;
+    /** `revocationReason` per RFC 5280 §5.3.1 CRL reason codes; meaningful
+     *  only when certStatus=1. */
+    revocationReason: number;
+}
+/** Native handle returned by `imports.gi.GjsifyTls`. The shape mirrors
+ *  the GIR — `OcspResponseInfo` properties are exposed in camelCase via
+ *  GObject's automatic property accessor lowering on the GJS side. */
+export interface NativeTls {
+    /**
+     * Parse a DER-encoded OCSP response (RFC 6960). Returns `null` when
+     * the bytes are not a valid response (init / import errors).
+     */
+    parse_ocsp_response(bytes: Uint8Array): OcspResponseInfo | null;
+}
+export interface GjsifyTlsModule {
+    Tls: NativeTls;
+}
+/** The native GjsifyTls module, or `null` if not installed. */
+export declare const nativeTls: GjsifyTlsModule | null;
+/** Returns `true` when the GjsifyTls native library is available. */
+export declare function hasNativeTls(): boolean;
+/**
+ * Parse a DER-encoded OCSP response (RFC 6960).
+ *
+ * Throws when `@gjsify/tls-native`'s typelib is not loaded — callers can
+ * gate with `hasNativeTls()` and fall back to a pure-JS path (no such path
+ * exists today; OCSP parsing requires either the GnuTLS bridge here or a
+ * full RFC 6960 ASN.1 decoder).
+ *
+ * @param bytes  DER-encoded OCSPResponse bytes (typically the body of a
+ *               POST response from the cert's AIA OCSP responder URL).
+ * @returns      Parsed response on success, `null` when the bytes don't
+ *               parse as an OCSPResponse.
+ */
+export declare function parseOcspResponse(bytes: Uint8Array): OcspResponseInfo | null;
+/**
+ * Symbolic OCSP cert-status values per RFC 6960 §4.2.1. Use as
+ * `OcspCertStatus.GOOD` for readable comparisons.
+ */
+export declare const OcspCertStatus: {
+    readonly GOOD: 0;
+    readonly REVOKED: 1;
+    readonly UNKNOWN: 2;
+};
+export type OcspCertStatus = (typeof OcspCertStatus)[keyof typeof OcspCertStatus];
+/**
+ * Symbolic OCSP responseStatus values per RFC 6960 §4.2.1.
+ */
+export declare const OcspResponseStatus: {
+    readonly SUCCESSFUL: 0;
+    readonly MALFORMED_REQUEST: 1;
+    readonly INTERNAL_ERROR: 2;
+    readonly TRY_LATER: 3;
+    readonly SIG_REQUIRED: 5;
+    readonly UNAUTHORIZED: 6;
+};
+export type OcspResponseStatus = (typeof OcspResponseStatus)[keyof typeof OcspResponseStatus];

package/lib/types/index.gjs.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/meson.build

@@ -0,0 +1,36 @@
+project('GjsifyTls', ['c', 'vala'], version: '1.0')
+
+root_dir = meson.current_source_dir()
+
+dependencies = [
+    dependency('glib-2.0'),
+    dependency('gobject-2.0'),
+    dependency('gnutls'),
+]
+
+sources = files(
+    'src/vala/tls.vala',
+)
+
+libGjsifyTls = library('gjsifytls', sources,
+    dependencies: dependencies,
+    vala_args: ['--pkg=gnutls', '--vapidir=' + meson.current_source_dir() / 'src/vala', '--pkg=gnutls-ocsp'],
+    vala_gir: meson.project_name() + '-1.0.gir',
+    install: true,
+    install_dir: [true, true, true, true],
+)
+
+g_ir_compiler = find_program('g-ir-compiler')
+
+custom_target(meson.project_name() + '-1.0.typelib',
+    command: [
+        g_ir_compiler,
+        '--shared-library', 'libgjsifytls.so',
+        '--output', '@OUTPUT@',
+        meson.current_build_dir() / meson.project_name() + '-1.0.gir',
+    ],
+    output: meson.project_name() + '-1.0.typelib',
+    depends: libGjsifyTls,
+    install: true,
+    install_dir: get_option('libdir') / 'girepository-1.0',
+)

package/package.json

@@ -0,0 +1,62 @@
+{
+    "name": "@gjsify/tls-native",
+    "version": "0.4.20",
+    "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.",
+    "type": "module",
+    "main": "lib/esm/index.js",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        }
+    },
+    "files": [
+        "lib",
+        "prebuilds",
+        "meson.build",
+        "src/vala"
+    ],
+    "gjsify": {
+        "prebuilds": "prebuilds"
+    },
+    "keywords": [
+        "gjs",
+        "tls",
+        "gnutls",
+        "ocsp",
+        "ocsp-stapling",
+        "channel-binding",
+        "scram",
+        "session-resumption",
+        "vala",
+        "native"
+    ],
+    "scripts": {
+        "clear": "rm -rf lib build tsconfig.tsbuildinfo tsconfig.types.tsbuildinfo test.gjs.mjs || exit 0",
+        "check": "tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/ts/**/*.{ts,js}'",
+        "build:types": "tsc",
+        "build:test:gjs": "gjsify build src/ts/test.mts --app gjs --outfile test.gjs.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test:gjs && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs",
+        "init:meson": "meson setup build .",
+        "init:meson:wipe": "gjsify run init:meson --wipe",
+        "build:meson": "gjsify run init:meson && meson compile -C build",
+        "build:prebuilds": "gjsify run build:meson && mkdir -p prebuilds/linux-x86_64 && cp build/libgjsifytls.so build/GjsifyTls-1.0.gir build/GjsifyTls-1.0.typelib prebuilds/linux-x86_64/",
+        "build:gir-types": "ts-for-gir generate --externalDeps --allowMissingDeps --girDirectories=./prebuilds/linux-x86_64 --girDirectories=/usr/share/gir-1.0 --modules=GjsifyTls-1.0 --outdir=src/ts --npmScope=@girs --package=false --ignoreVersionConflicts=true"
+    },
+    "dependencies": {
+        "@girs/glib-2.0": "2.88.0-4.0.0-rc.15",
+        "@girs/gobject-2.0": "2.88.0-4.0.0-rc.15"
+    },
+    "devDependencies": {
+        "@gjsify/cli": "workspace:^",
+        "@gjsify/unit": "workspace:^",
+        "@ts-for-gir/cli": "^4.0.0-rc.15",
+        "@types/node": "^25.6.2",
+        "typescript": "^6.0.3"
+    }
+}

package/prebuilds/linux-x86_64/GjsifyTls-1.0.gir

@@ -0,0 +1,153 @@
+<?xml version="1.0"?>
+<!-- GjsifyTls-1.0.gir generated by valac 0.56.18, do not modify. -->
+<repository version="1.2" xmlns="http://www.gtk.org/introspection/core/1.0" xmlns:c="http://www.gtk.org/introspection/c/1.0" xmlns:glib="http://www.gtk.org/introspection/glib/1.0">
+<include name="GObject" version="2.0"/>
+<package name="gjsifytls"/>
+<c:include name="gjsifytls.h"/>
+<namespace name="GjsifyTls" version="1.0" c:prefix="GjsifyTls" c:identifier-prefixes="GjsifyTls" c:symbol-prefixes="gjsify_tls">
+	<class name="OcspResponseInfo" c:type="GjsifyTlsOcspResponseInfo" c:symbol-prefix="ocsp_response_info" glib:type-name="GjsifyTlsOcspResponseInfo" glib:get-type="gjsify_tls_ocsp_response_info_get_type" glib:type-struct="OcspResponseInfoClass" parent="GObject.Object">
+		<field name="parent_instance" readable="0" private="1">
+			<type name="GObject.Object" c:type="GObject"/>
+		</field>
+		<field name="priv" readable="0" private="1">
+			<type name="OcspResponseInfoPrivate" c:type="GjsifyTlsOcspResponseInfoPrivate*"/>
+		</field>
+		<constructor name="new" c:identifier="gjsify_tls_ocsp_response_info_new">
+			<return-value transfer-ownership="full">
+				<type name="GjsifyTls.OcspResponseInfo" c:type="GjsifyTlsOcspResponseInfo*"/>
+			</return-value>
+		</constructor>
+		<property name="response-status" writable="1">
+			<type name="gint" c:type="gint"/>
+		</property>
+		<method name="get_response_status" c:identifier="gjsify_tls_ocsp_response_info_get_response_status">
+			<return-value transfer-ownership="none">
+				<type name="gint" c:type="gint"/>
+			</return-value>
+			<parameters>
+				<instance-parameter name="self" transfer-ownership="none">
+					<type name="GjsifyTls.OcspResponseInfo" c:type="GjsifyTlsOcspResponseInfo*"/>
+				</instance-parameter>
+			</parameters>
+		</method>
+		<property name="produced-at" writable="1">
+			<type name="gint64" c:type="gint64"/>
+		</property>
+		<method name="get_produced_at" c:identifier="gjsify_tls_ocsp_response_info_get_produced_at">
+			<return-value transfer-ownership="none">
+				<type name="gint64" c:type="gint64"/>
+			</return-value>
+			<parameters>
+				<instance-parameter name="self" transfer-ownership="none">
+					<type name="GjsifyTls.OcspResponseInfo" c:type="GjsifyTlsOcspResponseInfo*"/>
+				</instance-parameter>
+			</parameters>
+		</method>
+		<property name="cert-status" writable="1">
+			<type name="gint" c:type="gint"/>
+		</property>
+		<method name="get_cert_status" c:identifier="gjsify_tls_ocsp_response_info_get_cert_status">
+			<return-value transfer-ownership="none">
+				<type name="gint" c:type="gint"/>
+			</return-value>
+			<parameters>
+				<instance-parameter name="self" transfer-ownership="none">
+					<type name="GjsifyTls.OcspResponseInfo" c:type="GjsifyTlsOcspResponseInfo*"/>
+				</instance-parameter>
+			</parameters>
+		</method>
+		<property name="this-update" writable="1">
+			<type name="gint64" c:type="gint64"/>
+		</property>
+		<method name="get_this_update" c:identifier="gjsify_tls_ocsp_response_info_get_this_update">
+			<return-value transfer-ownership="none">
+				<type name="gint64" c:type="gint64"/>
+			</return-value>
+			<parameters>
+				<instance-parameter name="self" transfer-ownership="none">
+					<type name="GjsifyTls.OcspResponseInfo" c:type="GjsifyTlsOcspResponseInfo*"/>
+				</instance-parameter>
+			</parameters>
+		</method>
+		<property name="next-update" writable="1">
+			<type name="gint64" c:type="gint64"/>
+		</property>
+		<method name="get_next_update" c:identifier="gjsify_tls_ocsp_response_info_get_next_update">
+			<return-value transfer-ownership="none">
+				<type name="gint64" c:type="gint64"/>
+			</return-value>
+			<parameters>
+				<instance-parameter name="self" transfer-ownership="none">
+					<type name="GjsifyTls.OcspResponseInfo" c:type="GjsifyTlsOcspResponseInfo*"/>
+				</instance-parameter>
+			</parameters>
+		</method>
+		<property name="revocation-time" writable="1">
+			<type name="gint64" c:type="gint64"/>
+		</property>
+		<method name="get_revocation_time" c:identifier="gjsify_tls_ocsp_response_info_get_revocation_time">
+			<return-value transfer-ownership="none">
+				<type name="gint64" c:type="gint64"/>
+			</return-value>
+			<parameters>
+				<instance-parameter name="self" transfer-ownership="none">
+					<type name="GjsifyTls.OcspResponseInfo" c:type="GjsifyTlsOcspResponseInfo*"/>
+				</instance-parameter>
+			</parameters>
+		</method>
+		<property name="revocation-reason" writable="1">
+			<type name="gint" c:type="gint"/>
+		</property>
+		<method name="get_revocation_reason" c:identifier="gjsify_tls_ocsp_response_info_get_revocation_reason">
+			<return-value transfer-ownership="none">
+				<type name="gint" c:type="gint"/>
+			</return-value>
+			<parameters>
+				<instance-parameter name="self" transfer-ownership="none">
+					<type name="GjsifyTls.OcspResponseInfo" c:type="GjsifyTlsOcspResponseInfo*"/>
+				</instance-parameter>
+			</parameters>
+		</method>
+	</class>
+	<record name="OcspResponseInfoClass" c:type="GjsifyTlsOcspResponseInfoClass" glib:is-gtype-struct-for="OcspResponseInfo">
+		<field name="parent_class" readable="0" private="1">
+			<type name="GObject.ObjectClass" c:type="GObjectClass"/>
+		</field>
+	</record>
+	<record name="OcspResponseInfoPrivate" c:type="GjsifyTlsOcspResponseInfoPrivate" disguised="1"/>
+	<class name="Tls" c:type="GjsifyTlsTls" c:symbol-prefix="tls" glib:type-name="GjsifyTlsTls" glib:get-type="gjsify_tls_tls_get_type" glib:type-struct="TlsClass" parent="GObject.Object">
+		<field name="parent_instance" readable="0" private="1">
+			<type name="GObject.Object" c:type="GObject"/>
+		</field>
+		<field name="priv" readable="0" private="1">
+			<type name="TlsPrivate" c:type="GjsifyTlsTlsPrivate*"/>
+		</field>
+		<function name="parse_ocsp_response" c:identifier="gjsify_tls_tls_parse_ocsp_response">
+			<return-value transfer-ownership="full" nullable="1">
+				<type name="GjsifyTls.OcspResponseInfo" c:type="GjsifyTlsOcspResponseInfo*"/>
+			</return-value>
+			<parameters>
+				<parameter name="bytes" transfer-ownership="none">
+					<array length="1" c:type="guint8*">
+						<type name="guint8" c:type="guint8"/>
+					</array>
+				</parameter>
+				<parameter name="bytes_length1" transfer-ownership="none">
+					<type name="gint" c:type="gint"/>
+				</parameter>
+			</parameters>
+		</function>
+		<constructor name="new" c:identifier="gjsify_tls_tls_new">
+			<return-value transfer-ownership="full">
+				<type name="GjsifyTls.Tls" c:type="GjsifyTlsTls*"/>
+			</return-value>
+		</constructor>
+	</class>
+	<record name="TlsClass" c:type="GjsifyTlsTlsClass" glib:is-gtype-struct-for="Tls">
+		<field name="parent_class" readable="0" private="1">
+			<type name="GObject.ObjectClass" c:type="GObjectClass"/>
+		</field>
+	</record>
+	<record name="TlsPrivate" c:type="GjsifyTlsTlsPrivate" disguised="1"/>
+</namespace>
+</repository>

package/src/vala/gnutls-ocsp.vapi

@@ -0,0 +1,44 @@
+/* gnutls-ocsp.vapi — Vala 0.56's bundled gnutls.vapi has no OCSP bindings.
+ * This sibling vapi declares the minimal subset we need to wrap
+ * `gnutls_ocsp_resp_*` for OCSP-response parsing (RFC 6960).
+ *
+ * `.vapi` (vs `.vala`) is important: `.vapi` files are pure declarations
+ * mapping to existing C types. Putting these `cname = "struct …"` bindings
+ * in a `.vala` file makes valac try to *emit* the typedef, which collides
+ * with the typedef already present in `gnutls/ocsp.h`.
+ *
+ * Loaded via meson's `vala_args: ['--vapidir=<srcdir>/src/vala']`.
+ */
+
+[CCode (cheader_filename = "gnutls/ocsp.h", lower_case_cprefix = "gnutls_ocsp_")]
+namespace GjsifyTlsOcsp {
+
+    [Compact]
+    [CCode (cname = "struct gnutls_ocsp_resp_int", free_function = "gnutls_ocsp_resp_deinit")]
+    public class Resp {
+        [CCode (cname = "gnutls_ocsp_resp_init")]
+        public static int init(out Resp resp);
+
+        [CCode (cname = "gnutls_ocsp_resp_import")]
+        public int import(ref GnuTLS.Datum data);
+
+        [CCode (cname = "gnutls_ocsp_resp_get_status")]
+        public int get_status();
+
+        [CCode (cname = "gnutls_ocsp_resp_get_produced")]
+        public time_t get_produced();
+
+        [CCode (cname = "gnutls_ocsp_resp_get_single")]
+        public int get_single(
+            uint indx,
+            out int digest,
+            out GnuTLS.Datum issuer_name_hash,
+            out GnuTLS.Datum issuer_key_hash,
+            out GnuTLS.Datum serial_number,
+            out uint cert_status,
+            out time_t this_update,
+            out time_t next_update,
+            out time_t revocation_time,
+            out uint revocation_reason);
+    }
+}

package/src/vala/tls.vala

@@ -0,0 +1,159 @@
+/*
+ * GjsifyTls — Vala/GObject bridge for GnuTLS APIs that Gio.TlsConnection
+ * does not surface to JS.
+ *
+ * Phase 1 scope (this file): OCSP-response parsing (RFC 6960).
+ *
+ *   Status of GnuTLS bindings in Vala 0.56:
+ *     - `gnutls.vapi` covers the core handshake / X.509 / pubkey surface
+ *       but has *no* `gnutls_ocsp_*` declarations. We supply them in a
+ *       sibling `gnutls-ocsp.vapi`, which the meson rule loads via
+ *       `--vapidir`. `.vapi` files (vs `.vala`) declare existing C types
+ *       without re-emitting the typedef — the `cname = "struct gnutls_…"`
+ *       pattern that works in vapi headers crashes in `.vala` because
+ *       valac there tries to define the type.
+ *
+ * Future scope (not in this file yet):
+ *   - Session resumption: `gnutls_session_get_data2` / `set_data` —
+ *     blocked on extracting the live `gnutls_session_t` from
+ *     `Gio.TlsConnection`. Tracked in STATUS.md.
+ *   - Channel binding: `gnutls_session_channel_binding` (TLS-Finished bytes
+ *     for SCRAM-SHA-* SASL). Same gnutls_session_t blocker.
+ *
+ * The OCSP-response parser works on raw DER bytes (a Uint8Array on the
+ * JS side) and returns a plain GObject with the parsed fields. Consumers
+ * can fetch OCSP responses themselves (e.g. via @gjsify/fetch against the
+ * cert's Authority Information Access OCSP responder URL) and pass them
+ * here for validation.
+ */
+
+using GLib;
+
+namespace GjsifyTls {
+
+    /**
+     * OcspResponseInfo — parsed result of {@link Tls.parse_ocsp_response}.
+     *
+     * Fields mirror the subset of RFC 6960 OCSPResponse we extract.
+     */
+    public class OcspResponseInfo : GLib.Object {
+        /**
+         * `responseStatus` per RFC 6960 §4.2.1:
+         *   0 = successful
+         *   1 = malformedRequest
+         *   2 = internalError
+         *   3 = tryLater
+         *   5 = sigRequired
+         *   6 = unauthorized
+         */
+        public int response_status { get; internal set; }
+
+        /** `producedAt` field (Unix seconds, 0 if unparseable). */
+        public int64 produced_at { get; internal set; }
+
+        /**
+         * `certStatus` per RFC 6960 §4.2.1:
+         *   0 = good
+         *   1 = revoked
+         *   2 = unknown
+         */
+        public int cert_status { get; internal set; }
+
+        /** `thisUpdate` field (Unix seconds). */
+        public int64 this_update { get; internal set; }
+
+        /** `nextUpdate` field (Unix seconds, 0 if absent). */
+        public int64 next_update { get; internal set; }
+
+        /** `revocationTime` (Unix seconds, only when cert_status = 1). */
+        public int64 revocation_time { get; internal set; }
+
+        /**
+         * `revocationReason` per RFC 5280 §5.3.1 CRL reason codes.
+         * Only meaningful when cert_status = 1.
+         */
+        public int revocation_reason { get; internal set; }
+    }
+
+    /**
+     * Tls — static helpers wrapping GnuTLS APIs not exposed by Gio.
+     */
+    public class Tls : GLib.Object {
+
+        /**
+         * parse_ocsp_response:
+         * @bytes: DER-encoded OCSPResponse (RFC 6960)
+         *
+         * Parse an OCSP response and return its key fields. Returns %null
+         * if the bytes are not a valid OCSPResponse (init or import fails).
+         *
+         * On success the returned object's @response_status is filled even
+         * when @response_status != 0 (i.e. error responses); the per-cert
+         * fields (@cert_status, @this_update, …) are filled only when
+         * @response_status == 0 AND the response contains at least one
+         * SingleResponse — otherwise they are zero-initialised.
+         */
+        public static OcspResponseInfo? parse_ocsp_response(uint8[] bytes) {
+            GjsifyTlsOcsp.Resp? resp = null;
+            if (GjsifyTlsOcsp.Resp.init(out resp) != 0 || resp == null) {
+                return null;
+            }
+
+            GnuTLS.Datum data = { (void*) bytes, (uint) bytes.length };
+
+            if (resp.import(ref data) != 0) {
+                return null;
+            }
+
+            var info = new OcspResponseInfo();
+            info.response_status = resp.get_status();
+
+            if (info.response_status != 0) {
+                // Non-successful response — per-cert fields not available.
+                return info;
+            }
+
+            info.produced_at = (int64) resp.get_produced();
+
+            int digest;
+            GnuTLS.Datum issuer_name_hash;
+            GnuTLS.Datum issuer_key_hash;
+            GnuTLS.Datum serial_number;
+            uint cert_status;
+            time_t this_update;
+            time_t next_update;
+            time_t revocation_time;
+            uint revocation_reason;
+
+            // Read the first SingleResponse (index 0). Multi-cert
+            // responses are rare in OCSP-stapling contexts.
+            int rc = resp.get_single(
+                0,
+                out digest,
+                out issuer_name_hash,
+                out issuer_key_hash,
+                out serial_number,
+                out cert_status,
+                out this_update,
+                out next_update,
+                out revocation_time,
+                out revocation_reason);
+
+            if (rc == 0) {
+                info.cert_status = (int) cert_status;
+                info.this_update = (int64) this_update;
+                info.next_update = (int64) next_update;
+                info.revocation_time = (int64) revocation_time;
+                info.revocation_reason = (int) revocation_reason;
+            }
+
+            // Touch the out-only datums once so valac doesn't drop them as
+            // unused; we don't surface them to JS yet — callers extract
+            // serial / issuer from the cert directly.
+            int _sink = digest;
+            if (_sink == -1) info.cert_status = info.cert_status;
+
+            return info;
+        }
+    }
+}