@floegence/flowersec-core 0.21.1 → 0.22.1

package/README.md

@@ -1,6 +1,6 @@
 # @floegence/flowersec-core
 
-Flowersec core TypeScript library for building end-to-end encrypted, multiplexed connections over WebSocket in browsers and Node.js.
+Flowersec core TypeScript library for the complete portable Flowersec client/server contract in Node.js, plus the browser and Service Worker runtime owned by TypeScript.
 
 Status: experimental; not audited.
 
@@ -60,7 +60,17 @@ const reconnectConfig = createNodeReconnectConfig({
 Browser `requestConnectArtifact(...)`, `requestEntryConnectArtifact(...)`, and `ControlplaneRequestError` remain available from `@floegence/flowersec-core/browser` as stable aliases.
 
 High-level connects use `RequireTLS` by default. `AllowPlaintextForLoopback` permits only literal loopback
-targets without DNS resolution; `AllowPlaintext` is an explicit acceptance of pre-E2EE metadata exposure.
+targets without DNS resolution. Deliberate non-loopback `ws://` connections must use
+`createNetworkPlaintextPolicy(...)` with exact canonical IP literals and
+`PlaintextRiskAcceptance.acceptPreE2ECredentialExposure`. The unrestricted `AllowPlaintext` preset is deprecated.
+
+## Node endpoint and controlplane
+
+`@floegence/flowersec-core/node` exports the high-level endpoint APIs for accepted direct WebSockets and server-role tunnel grants. `@floegence/flowersec-core/endpoint` provides portable session and RPC serving, while `@floegence/flowersec-core/controlplane` provides bounded artifact envelopes, FST2 tokens, issuer rotation, and channel initialization.
+
+## Proxy
+
+`@floegence/flowersec-core/proxy` contains both portable HTTP/1 and WebSocket proxy protocols and the TypeScript-owned browser runtime. Node endpoint servers use `serveProxySession(...)`; browser applications use the Service Worker or controller bridge helpers without changing the portable stream contract.
 
 ## Docs
 

package/dist/browser/index.d.ts

@@ -1,7 +1,7 @@
 export type { ConnectBrowserOptions, DirectConnectBrowserOptions, TunnelConnectBrowserOptions } from "./connect.js";
 export { connectBrowser, connectDirectBrowser, connectTunnelBrowser } from "./connect.js";
-export { AllowPlaintext, AllowPlaintextForLoopback, RequireTLS, } from "../client-connect/transportSecurity.js";
-export type { TransportSecurityPolicy, TransportSecurityPolicyInput, TransportSecurityPolicyPreset, } from "../client-connect/transportSecurity.js";
+export { AllowPlaintext, AllowPlaintextForLoopback, createNetworkPlaintextPolicy, PlaintextRiskAcceptance, RequireTLS, } from "../client-connect/transportSecurity.js";
+export type { TransportSecurityPolicy, TransportSecurityPolicyInput, TransportSecurityPolicyPreset, NetworkPlaintextPolicyOptions, } from "../client-connect/transportSecurity.js";
 export type { ConnectArtifact, CorrelationContext, CorrelationKV, DirectClientConnectArtifact, ScopeMetadataEntry, TunnelClientConnectArtifact, } from "../connect/artifact.js";
 export { assertConnectArtifact } from "../connect/artifact.js";
 export type { ConnectArtifactRequestConfig, ControlplaneConfig, EntryConnectArtifactRequestConfig, EntryControlplaneConfig, } from "./controlplane.js";

package/dist/browser/index.js

@@ -1,5 +1,5 @@
 export { connectBrowser, connectDirectBrowser, connectTunnelBrowser } from "./connect.js";
-export { AllowPlaintext, AllowPlaintextForLoopback, RequireTLS, } from "../client-connect/transportSecurity.js";
+export { AllowPlaintext, AllowPlaintextForLoopback, createNetworkPlaintextPolicy, PlaintextRiskAcceptance, RequireTLS, } from "../client-connect/transportSecurity.js";
 export { assertConnectArtifact } from "../connect/artifact.js";
 export { ControlplaneRequestError, requestChannelGrant, requestConnectArtifact, requestEntryChannelGrant, requestEntryConnectArtifact, } from "./controlplane.js";
 export { createBrowserReconnectConfig, createDirectBrowserReconnectConfig, createTunnelBrowserReconnectConfig, } from "./reconnectConfig.js";

package/dist/client-connect/connectCore.js

@@ -2,6 +2,7 @@ import { clientHandshake } from "../e2ee/handshake.js";
 import { ByteReader } from "../yamux/byteReader.js";
 import { YamuxSession } from "../yamux/session.js";
 import { DEFAULT_YAMUX_LIMITS } from "../yamux/session.js";
+import { SDK_DEFAULTS } from "../defaults.js";
 import { RpcClient } from "../rpc/client.js";
 import { writeStreamHello } from "../streamhello/streamHello.js";
 import { emitObserverDiagnostic, normalizeObserver, nowSeconds } from "../observability/observer.js";
@@ -52,11 +53,11 @@ export async function connectCore(args) {
         const code = args.path === "tunnel" ? "missing_tunnel_url" : "missing_ws_url";
         throw new FlowersecError({ path: args.path, stage: "validate", code, message: "missing websocket url" });
     }
-    const connectTimeoutMs = args.opts.connectTimeoutMs ?? 10_000;
+    const connectTimeoutMs = args.opts.connectTimeoutMs ?? SDK_DEFAULTS.transport.connectTimeoutMs;
     if (!Number.isFinite(connectTimeoutMs) || connectTimeoutMs < 0) {
         invalidOption("connectTimeoutMs must be a non-negative number");
     }
-    const handshakeTimeoutMs = args.opts.handshakeTimeoutMs ?? 10_000;
+    const handshakeTimeoutMs = args.opts.handshakeTimeoutMs ?? SDK_DEFAULTS.transport.handshakeTimeoutMs;
     if (!Number.isFinite(handshakeTimeoutMs) || handshakeTimeoutMs < 0) {
         invalidOption("handshakeTimeoutMs must be a non-negative number");
     }
@@ -80,7 +81,7 @@ export async function connectCore(args) {
     if (!Number.isSafeInteger(maxOutboundBufferedBytes) || maxOutboundBufferedBytes < 0) {
         invalidOption("maxOutboundBufferedBytes must be a non-negative integer");
     }
-    const effectiveMaxRecordBytes = maxRecordBytes > 0 ? maxRecordBytes : (1 << 20);
+    const effectiveMaxRecordBytes = maxRecordBytes > 0 ? maxRecordBytes : SDK_DEFAULTS.e2ee.maxRecordBytes;
     const outboundRecordChunkBytes = args.opts.outboundRecordChunkBytes ?? 64 * 1024;
     if (!Number.isSafeInteger(outboundRecordChunkBytes) || outboundRecordChunkBytes <= 0 || outboundRecordChunkBytes > maxPlaintextBytes(effectiveMaxRecordBytes)) {
         invalidOption("outboundRecordChunkBytes must be a positive integer within maxRecordBytes");
@@ -183,7 +184,7 @@ export async function connectCore(args) {
                 suite,
                 psk,
                 clientFeatures,
-                maxHandshakePayload: maxHandshakePayload > 0 ? maxHandshakePayload : 8 * 1024,
+                maxHandshakePayload: maxHandshakePayload > 0 ? maxHandshakePayload : SDK_DEFAULTS.e2ee.maxHandshakePayloadBytes,
                 maxRecordBytes: effectiveMaxRecordBytes,
                 outboundRecordChunkBytes,
                 ...(maxBufferedBytes > 0 ? { maxBufferedBytes } : {}),

package/dist/client-connect/transportSecurity.d.ts

@@ -2,7 +2,16 @@ import type { ClientPath } from "../client.js";
 import { type ClientObserverLike } from "../observability/observer.js";
 export declare const RequireTLS: "require_tls";
 export declare const AllowPlaintextForLoopback: "allow_plaintext_for_loopback";
+/** @deprecated Use RequireTLS, AllowPlaintextForLoopback, or createNetworkPlaintextPolicy. */
 export declare const AllowPlaintext: "allow_plaintext";
+export declare const PlaintextRiskAcceptance: {
+    readonly acceptPreE2ECredentialExposure: "accept_pre_e2ee_credential_exposure";
+};
+export type PlaintextRiskAcceptance = typeof PlaintextRiskAcceptance[keyof typeof PlaintextRiskAcceptance];
+export type NetworkPlaintextPolicyOptions = Readonly<{
+    allowedHosts: readonly string[];
+    riskAcceptance: PlaintextRiskAcceptance;
+}>;
 export type TransportSecurityPolicyInput = Readonly<{
     path: ClientPath;
     scheme: "ws" | "wss";
@@ -11,6 +20,7 @@ export type TransportSecurityPolicyInput = Readonly<{
 }>;
 export type TransportSecurityPolicyPreset = typeof RequireTLS | typeof AllowPlaintextForLoopback | typeof AllowPlaintext;
 export type TransportSecurityPolicy = TransportSecurityPolicyPreset | ((input: TransportSecurityPolicyInput) => boolean | Promise<boolean>);
+export declare function createNetworkPlaintextPolicy(options: NetworkPlaintextPolicyOptions): TransportSecurityPolicy;
 export declare function enforceTransportSecurity(args: Readonly<{
     rawUrl: string;
     path: ClientPath;

package/dist/client-connect/transportSecurity.js

@@ -2,7 +2,21 @@ import { FlowersecError } from "../utils/errors.js";
 import { emitObserverDiagnostic } from "../observability/observer.js";
 export const RequireTLS = "require_tls";
 export const AllowPlaintextForLoopback = "allow_plaintext_for_loopback";
+/** @deprecated Use RequireTLS, AllowPlaintextForLoopback, or createNetworkPlaintextPolicy. */
 export const AllowPlaintext = "allow_plaintext";
+export const PlaintextRiskAcceptance = {
+    acceptPreE2ECredentialExposure: "accept_pre_e2ee_credential_exposure",
+};
+export function createNetworkPlaintextPolicy(options) {
+    if (options?.riskAcceptance !== PlaintextRiskAcceptance.acceptPreE2ECredentialExposure) {
+        throw new Error("network plaintext policy requires explicit pre-E2EE credential exposure acceptance");
+    }
+    if (!Array.isArray(options.allowedHosts) || options.allowedHosts.length === 0) {
+        throw new Error("network plaintext policy requires at least one allowed host");
+    }
+    const allowedHosts = new Set(options.allowedHosts.map(canonicalNetworkPlaintextHost));
+    return (input) => input.scheme === "wss" || (input.scheme === "ws" && allowedHosts.has(input.host));
+}
 export async function enforceTransportSecurity(args) {
     let target;
     try {
@@ -105,6 +119,81 @@ function isLiteralLoopbackHost(host) {
     }
     return octets[0] === 127;
 }
+function canonicalNetworkPlaintextHost(rawHost) {
+    const host = String(rawHost ?? "").trim();
+    if (host === "" || host !== host.toLowerCase() || /[@/?#%\[\]]/.test(host)) {
+        throw new Error(`invalid network plaintext allowed host ${JSON.stringify(rawHost)}`);
+    }
+    if (host.includes(":")) {
+        return canonicalNetworkIPv6Host(host);
+    }
+    const octets = canonicalIPv4Octets(host);
+    const firstOctet = octets[0];
+    const secondOctet = octets[1];
+    if (firstOctet == null || secondOctet == null) {
+        throw new Error(`network plaintext allowed host must be a canonical IP literal: ${JSON.stringify(rawHost)}`);
+    }
+    if (firstOctet === 127 || (firstOctet === 169 && secondOctet === 254) || firstOctet >= 224 || octets.every((value) => value === 0)) {
+        throw new Error(`network plaintext allowed host must be a non-loopback unicast IP literal: ${JSON.stringify(rawHost)}`);
+    }
+    return host;
+}
+function canonicalIPv4Octets(host) {
+    const parts = host.split(".");
+    if (parts.length !== 4) {
+        throw new Error(`network plaintext allowed host must be a canonical IP literal: ${JSON.stringify(host)}`);
+    }
+    const octets = parts.map((part) => {
+        if (!/^(0|[1-9]\d{0,2})$/.test(part)) {
+            throw new Error(`network plaintext allowed host must be a canonical IP literal: ${JSON.stringify(host)}`);
+        }
+        const value = Number(part);
+        if (value > 255) {
+            throw new Error(`network plaintext allowed host must be a canonical IP literal: ${JSON.stringify(host)}`);
+        }
+        return value;
+    });
+    return octets;
+}
+function canonicalNetworkIPv6Host(host) {
+    let parsed;
+    try {
+        parsed = new URL(`http://[${host}]/`);
+    }
+    catch {
+        throw new Error(`network plaintext allowed host must be a canonical IP literal: ${JSON.stringify(host)}`);
+    }
+    const canonical = parsed.hostname.replace(/^\[|\]$/g, "").toLowerCase();
+    if (canonical !== host) {
+        throw new Error(`network plaintext allowed host must be a canonical IP literal: ${JSON.stringify(host)}`);
+    }
+    const words = expandIPv6Words(canonical);
+    const unspecified = words.every((word) => word === 0);
+    const loopback = words.slice(0, 7).every((word) => word === 0) && words[7] === 1;
+    const mappedIPv4 = words.slice(0, 5).every((word) => word === 0) && words[5] === 0xffff;
+    const multicast = (words[0] & 0xff00) === 0xff00;
+    const linkLocal = (words[0] & 0xffc0) === 0xfe80;
+    if (unspecified || loopback || mappedIPv4 || multicast || linkLocal) {
+        throw new Error(`network plaintext allowed host must be a non-loopback unicast IP literal: ${JSON.stringify(host)}`);
+    }
+    return canonical;
+}
+function expandIPv6Words(host) {
+    const halves = host.split("::");
+    if (halves.length > 2)
+        throw new Error("invalid IPv6 host");
+    const left = halves[0] === "" ? [] : halves[0].split(":");
+    const right = halves.length === 1 || halves[1] === "" ? [] : halves[1].split(":");
+    const missing = 8 - left.length - right.length;
+    if ((halves.length === 1 && missing !== 0) || (halves.length === 2 && missing < 1)) {
+        throw new Error("invalid IPv6 host");
+    }
+    const words = [...left, ...Array.from({ length: missing }, () => "0"), ...right].map((part) => Number.parseInt(part, 16));
+    if (words.length !== 8 || words.some((word) => !Number.isInteger(word) || word < 0 || word > 0xffff)) {
+        throw new Error("invalid IPv6 host");
+    }
+    return words;
+}
 function detectRuntime() {
     if (typeof window !== "undefined" && typeof window.document !== "undefined")
         return "browser";

package/dist/controlplane/channelInit.d.ts

@@ -0,0 +1,27 @@
+import type { ChannelInitGrant, Suite } from "../gen/flowersec/controlplane/v1.gen.js";
+import type { IssuerKeyset } from "./issuer.js";
+export declare const CHANNEL_INIT_WINDOW_SECONDS = 120;
+export declare const DEFAULT_IDLE_TIMEOUT_SECONDS = 60;
+export declare const DEFAULT_TOKEN_EXP_SECONDS = 60;
+export type ChannelInitParams = Readonly<{
+    tunnelUrl: string;
+    tunnelAudience: string;
+    issuerId: string;
+    tokenExpSeconds?: number;
+    idleTimeoutSeconds?: number;
+    clockSkewMs?: number;
+    allowedSuites?: readonly Suite[];
+    defaultSuite?: Suite;
+}>;
+export declare class ChannelInitService {
+    private readonly issuer;
+    private readonly params;
+    private readonly nowUnixS;
+    constructor(issuer: IssuerKeyset, params: ChannelInitParams, nowUnixS?: () => number);
+    issue(channelIdInput: string): Readonly<{
+        client: ChannelInitGrant;
+        server: ChannelInitGrant;
+    }>;
+    reissue(grant: ChannelInitGrant): ChannelInitGrant;
+    private signRoleToken;
+}

package/dist/controlplane/channelInit.js

@@ -0,0 +1,116 @@
+import { Role } from "../gen/flowersec/controlplane/v1.gen.js";
+import { base64urlEncode } from "../utils/base64url.js";
+export const CHANNEL_INIT_WINDOW_SECONDS = 120;
+export const DEFAULT_IDLE_TIMEOUT_SECONDS = 60;
+export const DEFAULT_TOKEN_EXP_SECONDS = 60;
+export class ChannelInitService {
+    issuer;
+    params;
+    nowUnixS;
+    constructor(issuer, params, nowUnixS = () => Math.floor(Date.now() / 1000)) {
+        this.issuer = issuer;
+        this.params = params;
+        this.nowUnixS = nowUnixS;
+    }
+    issue(channelIdInput) {
+        const params = normalizeParams(this.params);
+        const channelId = normalizeChannelId(channelIdInput);
+        const psk = crypto.getRandomValues(new Uint8Array(32));
+        let pskB64u;
+        try {
+            pskB64u = base64urlEncode(psk);
+        }
+        finally {
+            psk.fill(0);
+        }
+        const now = normalizeNow(this.nowUnixS());
+        const initExp = now + CHANNEL_INIT_WINDOW_SECONDS;
+        const grant = (role, token) => ({
+            tunnel_url: params.tunnelUrl,
+            channel_id: channelId,
+            channel_init_expire_at_unix_s: initExp,
+            idle_timeout_seconds: params.idleTimeoutSeconds,
+            role,
+            token,
+            e2ee_psk_b64u: pskB64u,
+            allowed_suites: [...params.allowedSuites],
+            default_suite: params.defaultSuite,
+        });
+        return {
+            client: grant(Role.Role_client, this.signRoleToken(channelId, Role.Role_client, initExp, params.idleTimeoutSeconds, params.tokenExpSeconds, now, params)),
+            server: grant(Role.Role_server, this.signRoleToken(channelId, Role.Role_server, initExp, params.idleTimeoutSeconds, params.tokenExpSeconds, now, params)),
+        };
+    }
+    reissue(grant) {
+        const params = normalizeParams(this.params);
+        if (grant.idle_timeout_seconds <= 0 || (grant.role !== Role.Role_client && grant.role !== Role.Role_server))
+            throw new Error("invalid grant");
+        const now = normalizeNow(this.nowUnixS());
+        const skewSeconds = Math.ceil(params.clockSkewMs / 1000);
+        if (now > grant.channel_init_expire_at_unix_s + skewSeconds)
+            throw new Error("channel init expired");
+        return {
+            ...grant,
+            token: this.signRoleToken(normalizeChannelId(grant.channel_id), grant.role, grant.channel_init_expire_at_unix_s, grant.idle_timeout_seconds, params.tokenExpSeconds, now, params),
+        };
+    }
+    signRoleToken(channelId, role, initExp, idleTimeoutSeconds, tokenExpSeconds, now, params) {
+        const iat = Math.min(now, initExp);
+        const exp = Math.min(initExp, iat + tokenExpSeconds);
+        const tokenId = crypto.getRandomValues(new Uint8Array(24));
+        try {
+            return this.issuer.sign({
+                aud: params.tunnelAudience,
+                iss: params.issuerId,
+                channel_id: channelId,
+                role: role,
+                token_id: base64urlEncode(tokenId),
+                init_exp: initExp,
+                idle_timeout_seconds: idleTimeoutSeconds,
+                iat,
+                exp,
+            });
+        }
+        finally {
+            tokenId.fill(0);
+        }
+    }
+}
+function normalizeParams(params) {
+    const tunnelUrl = params.tunnelUrl.trim();
+    const tunnelAudience = params.tunnelAudience.trim();
+    const issuerId = params.issuerId.trim();
+    if (tunnelUrl === "")
+        throw new Error("missing tunnel URL");
+    if (tunnelAudience === "")
+        throw new Error("missing tunnel audience");
+    if (issuerId === "")
+        throw new Error("missing issuer ID");
+    const tokenExpSeconds = normalizeNonNegative("tokenExpSeconds", params.tokenExpSeconds ?? 0) || DEFAULT_TOKEN_EXP_SECONDS;
+    const idleTimeoutSeconds = normalizeNonNegative("idleTimeoutSeconds", params.idleTimeoutSeconds ?? 0) || DEFAULT_IDLE_TIMEOUT_SECONDS;
+    const clockSkewMs = normalizeNonNegative("clockSkewMs", params.clockSkewMs ?? 0);
+    const allowedSuites = [...new Set(params.allowedSuites?.length ? params.allowedSuites : [1])];
+    for (const suite of allowedSuites)
+        if (suite !== 1 && suite !== 2)
+            throw new Error("unsupported suite");
+    const defaultSuite = params.defaultSuite ?? allowedSuites[0];
+    if (!allowedSuites.includes(defaultSuite))
+        throw new Error("default suite not allowed");
+    return { tunnelUrl, tunnelAudience, issuerId, tokenExpSeconds, idleTimeoutSeconds, clockSkewMs, allowedSuites, defaultSuite };
+}
+function normalizeChannelId(input) {
+    const value = input.trim();
+    if (value === "" || new TextEncoder().encode(value).length > 256)
+        throw new Error("invalid channel ID");
+    return value;
+}
+function normalizeNonNegative(name, value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error(`${name} must be a non-negative integer`);
+    return value;
+}
+function normalizeNow(value) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new Error("invalid clock");
+    return value;
+}

package/dist/controlplane/http.d.ts

@@ -0,0 +1,16 @@
+export type ArtifactRequest = Readonly<{
+    endpoint_id: string;
+    payload?: Record<string, unknown>;
+    correlation?: Readonly<{
+        trace_id?: string;
+    }>;
+}>;
+export declare class ControlplaneCodecError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare function decodeArtifactRequest(contentType: string, body: Uint8Array, maxBodyBytes?: number): ArtifactRequest;
+export declare function encodeArtifactEnvelope(artifact: unknown): Uint8Array;
+export declare function encodeControlplaneError(code: string, message: string): Uint8Array;
+export declare function bearerToken(authorization: string): string | undefined;

package/dist/controlplane/http.js

@@ -0,0 +1,59 @@
+import { assertConnectArtifact } from "../connect/artifact.js";
+import { SDK_DEFAULTS } from "../defaults.js";
+export class ControlplaneCodecError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "ControlplaneCodecError";
+    }
+}
+export function decodeArtifactRequest(contentType, body, maxBodyBytes = SDK_DEFAULTS.controlplane.maxRequestBodyBytes) {
+    if (contentType.split(";", 1)[0]?.trim().toLowerCase() !== "application/json") {
+        throw new ControlplaneCodecError(415, "unsupported_media_type", "content type must be application/json");
+    }
+    if (body.length > maxBodyBytes)
+        throw new ControlplaneCodecError(413, "body_too_large", `request body exceeds ${maxBodyBytes} bytes`);
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder().decode(body));
+    }
+    catch {
+        throw new ControlplaneCodecError(400, "invalid_json", "malformed JSON request body");
+    }
+    if (typeof value !== "object" || value == null || Array.isArray(value))
+        throw new ControlplaneCodecError(400, "invalid_json", "request body must be a JSON object");
+    const input = value;
+    const endpointId = typeof input["endpoint_id"] === "string" ? input["endpoint_id"].trim() : "";
+    if (endpointId === "")
+        throw new ControlplaneCodecError(400, "invalid_request", "bad endpoint_id");
+    const payload = input["payload"];
+    if (payload !== undefined && (typeof payload !== "object" || payload == null || Array.isArray(payload)))
+        throw new ControlplaneCodecError(400, "invalid_request", "bad payload");
+    const correlation = input["correlation"];
+    if (correlation !== undefined && (typeof correlation !== "object" || correlation == null || Array.isArray(correlation)))
+        throw new ControlplaneCodecError(400, "invalid_request", "bad correlation");
+    const traceId = typeof correlation?.["trace_id"] === "string"
+        ? String(correlation["trace_id"]).trim()
+        : "";
+    return {
+        endpoint_id: endpointId,
+        ...(payload === undefined ? {} : { payload: payload }),
+        ...(traceId === "" ? {} : { correlation: { trace_id: traceId } }),
+    };
+}
+export function encodeArtifactEnvelope(artifact) {
+    return new TextEncoder().encode(JSON.stringify({ connect_artifact: assertConnectArtifact(artifact) }));
+}
+export function encodeControlplaneError(code, message) {
+    return new TextEncoder().encode(JSON.stringify({ error: { code, message } }));
+}
+export function bearerToken(authorization) {
+    const value = authorization.trim();
+    if (!value.startsWith("Bearer "))
+        return undefined;
+    const token = value.slice("Bearer ".length).trim();
+    return token === "" ? undefined : token;
+}

package/dist/controlplane/index.d.ts

@@ -1,2 +1,6 @@
 export type { ArtifactRequestCorrelation, ConnectArtifactEnvelope, ControlplaneBaseConfig, ControlplaneErrorEnvelope, RequestConnectArtifactInput, RequestEntryConnectArtifactInput, } from "./request.js";
 export { ControlplaneRequestError, DEFAULT_CONNECT_ARTIFACT_PATH, DEFAULT_ENTRY_CONNECT_ARTIFACT_PATH, requestConnectArtifact, requestEntryConnectArtifact, } from "./request.js";
+export * from "./token.js";
+export * from "./issuer.js";
+export * from "./channelInit.js";
+export * from "./http.js";

package/dist/controlplane/index.js

@@ -1 +1,5 @@
 export { ControlplaneRequestError, DEFAULT_CONNECT_ARTIFACT_PATH, DEFAULT_ENTRY_CONNECT_ARTIFACT_PATH, requestConnectArtifact, requestEntryConnectArtifact, } from "./request.js";
+export * from "./token.js";
+export * from "./issuer.js";
+export * from "./channelInit.js";
+export * from "./http.js";

package/dist/controlplane/issuer.d.ts

@@ -0,0 +1,15 @@
+import { type TokenPayload } from "./token.js";
+export declare class IssuerKeyset {
+    private kid;
+    private signingSeed;
+    constructor(kid: string, signingSeed: Uint8Array);
+    static random(kid: string): IssuerKeyset;
+    currentKID(): string;
+    publicKeys(): ReadonlyMap<string, Uint8Array>;
+    sign(payload: Omit<TokenPayload, "kid"> & Readonly<{
+        kid?: string;
+    }>): string;
+    rotate(kid: string, signingSeed: Uint8Array): void;
+    exportTunnelKeyset(): Uint8Array;
+    dispose(): void;
+}

package/dist/controlplane/issuer.js

@@ -0,0 +1,53 @@
+import { ed25519 } from "@noble/curves/ed25519";
+import { base64urlEncode } from "../utils/base64url.js";
+import { signToken } from "./token.js";
+export class IssuerKeyset {
+    kid;
+    signingSeed;
+    constructor(kid, signingSeed) {
+        this.kid = normalizeKid(kid);
+        if (signingSeed.length !== 32)
+            throw new TypeError("Ed25519 signing seed must be 32 bytes");
+        this.signingSeed = signingSeed.slice();
+    }
+    static random(kid) {
+        const seed = crypto.getRandomValues(new Uint8Array(32));
+        try {
+            return new IssuerKeyset(kid, seed);
+        }
+        finally {
+            seed.fill(0);
+        }
+    }
+    currentKID() {
+        return this.kid;
+    }
+    publicKeys() {
+        return new Map([[this.kid, ed25519.getPublicKey(this.signingSeed)]]);
+    }
+    sign(payload) {
+        return signToken(this.signingSeed, { ...payload, kid: this.kid });
+    }
+    rotate(kid, signingSeed) {
+        const nextKID = normalizeKid(kid);
+        if (signingSeed.length !== 32)
+            throw new TypeError("Ed25519 signing seed must be 32 bytes");
+        const nextSeed = signingSeed.slice();
+        this.signingSeed.fill(0);
+        this.kid = nextKID;
+        this.signingSeed = nextSeed;
+    }
+    exportTunnelKeyset() {
+        const keys = [...this.publicKeys()].map(([kid, publicKey]) => ({ kid, pubkey_b64u: base64urlEncode(publicKey) }));
+        return new TextEncoder().encode(JSON.stringify({ keys }, null, 2));
+    }
+    dispose() {
+        this.signingSeed.fill(0);
+    }
+}
+function normalizeKid(kid) {
+    const value = kid.trim();
+    if (value === "")
+        throw new TypeError("key ID is required");
+    return value;
+}

package/dist/controlplane/request.js

@@ -1,4 +1,5 @@
 import { assertConnectArtifact } from "../connect/artifact.js";
+import { SDK_DEFAULTS } from "../defaults.js";
 export class ControlplaneRequestError extends Error {
     status;
     code;
@@ -13,7 +14,7 @@ export class ControlplaneRequestError extends Error {
 }
 export const DEFAULT_CONNECT_ARTIFACT_PATH = "/v1/connect/artifact";
 export const DEFAULT_ENTRY_CONNECT_ARTIFACT_PATH = "/v1/connect/artifact/entry";
-const DEFAULT_MAX_CONTROLPLANE_RESPONSE_BYTES = 1 << 20;
+const DEFAULT_MAX_CONTROLPLANE_RESPONSE_BYTES = SDK_DEFAULTS.controlplane.maxResponseBodyBytes;
 class ControlplaneResponseTooLargeError extends Error {
     constructor(maxBytes) {
         super(`controlplane response exceeded ${maxBytes} bytes`);

package/dist/controlplane/token.d.ts

@@ -0,0 +1,33 @@
+export declare const TOKEN_PREFIX = "FST2";
+export type TokenPayload = Readonly<{
+    kid: string;
+    aud: string;
+    iss?: string;
+    channel_id: string;
+    role: 1 | 2;
+    token_id: string;
+    init_exp: number;
+    idle_timeout_seconds: number;
+    iat: number;
+    exp: number;
+}>;
+export type ParsedToken = Readonly<{
+    payload: TokenPayload;
+    signed: Uint8Array;
+    signature: Uint8Array;
+}>;
+export type TokenVerifyOptions = Readonly<{
+    nowUnixS?: number;
+    audience?: string;
+    issuer?: string;
+    clockSkewMs?: number;
+}>;
+export type TokenKeyLookup = ReadonlyMap<string, Uint8Array> | ((kid: string) => Uint8Array | undefined);
+export declare class TokenError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+export declare function signToken(signingSeed: Uint8Array, payload: TokenPayload): string;
+export declare function parseToken(token: string): ParsedToken;
+export declare function verifyToken(token: string, keys: TokenKeyLookup, options?: TokenVerifyOptions): TokenPayload;
+export declare function equalSignedTokenPart(left: string, right: string): boolean;