@fastls/fastls 0.13.0 → 0.15.0

package/README.md

@@ -1,5 +1,9 @@
 # Fastls Node.js SDK
 
+Python 0.6.0 / Node 0.15.0 支持显式 H3 与可信 Session 地址策略组合，需原生 `http3_address_policy_v1`；默认校验证书，旧库在分配资源前拒绝。详见 [组合契约](https://github.com/FastTLS/fastls-ffi/blob/main/H3_POLICY.zh-CN.md)。
+
+Node 0.14.0 增加完整 Spec 的 H2 首流编号与初始流窗口配置，并导出 `HTTP2StreamConfig` 类型。省略保持旧行为，需要 `http2.stream.v1` 和原生 `http2_stream_v1`；转换、Bundle/Store、Session/fetch 共用契约。旧原生库明确拒绝，窗口预算及候选采用边界见 [中文契约](https://github.com/FastTLS/fastls-ffi/blob/main/FINGERPRINTS.zh-CN.md)。
+
 Node 0.11.0 起支持 Session `addressPolicy`、`profileSpec: new ProfileSpec(...)` 和
 `httpVersion: "h3"`；Session/fetch 可选择完整 Spec 或显式协议。
 `addressPolicy` 只能创建可信 owner，不能由 `session.fetch()` 或请求替换。
@@ -37,7 +41,7 @@ Node.js 22+ 的 Fastls C ABI v1 绑定，提供 Promise API、TypeScript 声明
 安装指定版本：
 
 ```sh
-npm install @fastls/fastls@0.13.0
+npm install @fastls/fastls@0.15.0
 ```
 
 主包通过同版本的可选依赖自动安装当前平台的 Fastls 原生库。保留 optional dependencies；支持 Windows x64、Linux glibc x64/arm64、macOS x64/arm64。Linux musl 和其它架构没有内置包。具体系统最低版本见原生包的 `native/manifest.json`。

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { RetryPolicy } from "./retry.js";
 export { ProfileBundle, ProfileStore } from "./profile-store.js";
 export type { RetryOptions } from "./retry.js";
 export { ProfileSpec } from "./profiles.js";
-export type { AddressPolicy } from "./profiles.js";
+export type { AddressPolicy, HTTP2StreamConfig } from "./profiles.js";
 export { fetch } from "./fetch.js";
 export type { FetchOptions, FetchResponse } from "./fetch.js";
 export type { SessionOptions, RequestOptions, DuplexOptions, Stats } from "./session.js";

package/dist/profiles.d.ts

@@ -6,6 +6,13 @@ export interface AddressPolicy {
     readonly allow_cidrs?: readonly string[];
     readonly deny_cidrs?: readonly string[];
 }
+/** Optional stream settings within a complete schema-v1 profile. */
+export interface HTTP2StreamConfig {
+    /** 0 or omitted selects stream 1; other values are odd, up to 2^31-1. */
+    readonly first_stream_id?: number;
+    /** Receive credit sent once after initial request HEADERS; 0 disables it. */
+    readonly stream_window_increment?: number;
+}
 /** Explicit snapshot of a complete schema-v1 profile, validated by the core. */
 export declare class ProfileSpec {
     private readonly snapshot;
@@ -16,4 +23,6 @@ export declare class ProfileSpec {
         library?: string;
     }): ProfileSpec;
     toJSON(): Record<string, unknown>;
+    /** @internal Capability negotiation happens before allocating a session. */
+    nativeCapabilities(): string[];
 }

package/dist/profiles.js

@@ -20,8 +20,17 @@ class ProfileSpec {
             throw new TypeError("ja3 and h2 must be strings");
         if (Object.keys(options).some(key => !["ja3", "h2", "library"].includes(key)))
             throw new TypeError("unknown fingerprint option");
-        return new ProfileSpec(native_js_1.Native.load(library).adaptProfile({ schema_version: 1, base: base.toJSON(), ja3, h2 }));
+        const native = native_js_1.Native.load(library);
+        native.requireCapabilities(base.nativeCapabilities());
+        return new ProfileSpec(native.adaptProfile({ schema_version: 1, base: base.toJSON(), ja3, h2 }));
     }
     toJSON() { return JSON.parse(this.snapshot); }
+    /** @internal Capability negotiation happens before allocating a session. */
+    nativeCapabilities() {
+        const value = this.toJSON();
+        const stream = value.http2?.first_stream_id || value.http2?.stream_window_increment ||
+            (Array.isArray(value.capabilities?.required_features) && value.capabilities.required_features.includes("http2.stream.v1"));
+        return stream ? ["profile_spec_v1", "http2_stream_v1"] : ["profile_spec_v1"];
+    }
 }
 exports.ProfileSpec = ProfileSpec;

package/dist/session.d.ts

@@ -75,6 +75,7 @@ export declare class Session {
     static open(options?: SessionOptions): Promise<Session>;
     readonly notificationMode: "async-events" | "poll";
     readonly cookies: Cookies;
+    private readonly hasAddressPolicy;
     private readonly native;
     private readonly handle;
     private readonly profile;

package/dist/session.js

@@ -66,6 +66,7 @@ class Session {
     }
     notificationMode;
     cookies;
+    hasAddressPolicy;
     native;
     handle;
     profile;
@@ -87,6 +88,7 @@ class Session {
     constructor(options = {}) {
         if (options.retry !== undefined && !(options.retry instanceof retry_js_1.RetryPolicy))
             throw new TypeError("retry must be RetryPolicy");
+        this.hasAddressPolicy = options.addressPolicy !== undefined;
         this.retry = options.retry;
         this.proxy = proxyValue(options.proxy);
         this.proxyCaPem = proxyTrust(options.proxyCaFile);
@@ -129,11 +131,13 @@ class Session {
         }
         if (options.profileSpec !== undefined) {
             configuration.profile_spec = options.profileSpec.toJSON();
-            required.push("profile_spec_v1");
+            required.push(...options.profileSpec.nativeCapabilities());
         }
         if (options.httpVersion === "h3") {
             configuration.http_version = "h3";
             required.push("http3_v1");
+            if (this.hasAddressPolicy && options.httpVersion === "h3")
+                required.push("http3_address_policy_v1");
         }
         if (required.length) {
             this.native.requireCapabilities(required);
@@ -267,11 +271,13 @@ class Session {
             throw new TypeError("profile and profileSpec are mutually exclusive");
         const required = [];
         if (options.profileSpec !== undefined)
-            required.push("profile_spec_v1");
+            required.push(...options.profileSpec.nativeCapabilities());
         if (options.httpVersion !== undefined) {
             if (!["auto", "h3"].includes(options.httpVersion))
                 throw new TypeError("httpVersion must be auto or h3");
             required.push("http3_v1");
+            if (this.hasAddressPolicy && options.httpVersion === "h3")
+                required.push("http3_address_policy_v1");
         }
         if (required.length)
             this.native.requireCapabilities(required);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastls/fastls",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Node.js bindings for the Fastls C ABI",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -35,10 +35,10 @@
     "registry": "https://registry.npmjs.org/"
   },
   "optionalDependencies": {
-    "@fastls/fastls-win32-x64": "0.13.0",
-    "@fastls/fastls-linux-x64-glibc": "0.13.0",
-    "@fastls/fastls-linux-arm64-glibc": "0.13.0",
-    "@fastls/fastls-darwin-x64": "0.13.0",
-    "@fastls/fastls-darwin-arm64": "0.13.0"
+    "@fastls/fastls-win32-x64": "0.15.0",
+    "@fastls/fastls-linux-x64-glibc": "0.15.0",
+    "@fastls/fastls-linux-arm64-glibc": "0.15.0",
+    "@fastls/fastls-darwin-x64": "0.15.0",
+    "@fastls/fastls-darwin-arm64": "0.15.0"
   }
 }