@floegence/flowersec-core 0.17.2 → 0.19.0

package/README.md

@@ -1,6 +1,6 @@
 # @floegence/flowersec-core
 
-Flowersec core TypeScript library for building an end-to-end encrypted, multiplexed connection over WebSocket (browser-friendly).
+Flowersec core TypeScript library for building end-to-end encrypted, multiplexed connections over WebSocket in browsers and Node.js.
 
 Status: experimental; not audited.
 
@@ -10,33 +10,58 @@ Status: experimental; not audited.
 npm install @floegence/flowersec-core
 ```
 
-## Usage
+## Recommended usage
 
-Browser (recommended):
+Browser:
 
 ```ts
 import { connectBrowser } from "@floegence/flowersec-core/browser";
+import { requestConnectArtifact } from "@floegence/flowersec-core/controlplane";
 
-const grant = await fetch("/api/flowersec/channel/init", { method: "POST" }).then((r) => r.json());
-const client = await connectBrowser(grant);
+const artifact = await requestConnectArtifact({
+  endpointId: "env_demo",
+});
+
+const client = await connectBrowser(artifact);
 await client.ping();
 client.close();
 ```
 
-Node.js (recommended):
+Node.js:
 
 ```ts
-import { connectNode } from "@floegence/flowersec-core/node";
+import { connectNode, createNodeReconnectConfig } from "@floegence/flowersec-core/node";
+import { requestConnectArtifact } from "@floegence/flowersec-core/controlplane";
+
+const artifact = await requestConnectArtifact({
+  baseUrl: "https://your-app.example/api/flowersec",
+  endpointId: "env_demo",
+});
 
-const grant = await fetch("https://your-app.example/api/flowersec/channel/init", { method: "POST" }).then((r) => r.json());
-const client = await connectNode(grant, { origin: "https://your-app.example" });
+const client = await connectNode(artifact, {
+  origin: "https://your-app.example",
+});
 await client.ping();
 client.close();
+
+const reconnectConfig = createNodeReconnectConfig({
+  artifactControlplane: {
+    baseUrl: "https://your-app.example/api/flowersec",
+    endpointId: "env_demo",
+  },
+  connect: {
+    origin: "https://your-app.example",
+  },
+});
 ```
 
+Browser `requestConnectArtifact(...)`, `requestEntryConnectArtifact(...)`, and `ControlplaneRequestError` remain available from `@floegence/flowersec-core/browser` as stable aliases.
+
 ## Docs
 
 - Frontend quickstart: `docs/FRONTEND_QUICKSTART.md`
 - Integration guide: `docs/INTEGRATION_GUIDE.md`
 - API surface contract: `docs/API_SURFACE.md`
+- Controlplane artifact fetch: `docs/CONTROLPLANE_ARTIFACT_FETCH.md`
 - Error model: `docs/ERROR_MODEL.md`
+- Migration guide: `docs/V0_19_MIGRATION.md`

package/dist/browser/controlplane.d.ts

@@ -1,28 +1,15 @@
 import { type ChannelInitGrant } from "../facade.js";
-type FetchLike = typeof fetch;
-type BaseControlplaneRequestConfig = Readonly<{
-    baseUrl?: string;
+import type { ControlplaneBaseConfig as SharedControlplaneBaseConfig, RequestConnectArtifactInput, RequestEntryConnectArtifactInput } from "../controlplane/request.js";
+export { ControlplaneRequestError, requestConnectArtifact, requestEntryConnectArtifact, } from "../controlplane/request.js";
+type BaseControlplaneRequestConfig = SharedControlplaneBaseConfig & Readonly<{
     endpointId: string;
     payload?: Record<string, unknown>;
-    headers?: HeadersInit;
-    credentials?: RequestCredentials;
-    fetch?: FetchLike;
 }>;
 export type ControlplaneConfig = BaseControlplaneRequestConfig;
 export type EntryControlplaneConfig = BaseControlplaneRequestConfig & Readonly<{
     entryTicket: string;
 }>;
-export declare class ControlplaneRequestError extends Error {
-    readonly status: number;
-    readonly code: string;
-    readonly responseBody: unknown;
-    constructor(args: Readonly<{
-        status: number;
-        message: string;
-        code?: string;
-        responseBody?: unknown;
-    }>);
-}
+export type ConnectArtifactRequestConfig = RequestConnectArtifactInput;
+export type EntryConnectArtifactRequestConfig = RequestEntryConnectArtifactInput;
 export declare function requestChannelGrant(config: ControlplaneConfig): Promise<ChannelInitGrant>;
 export declare function requestEntryChannelGrant(config: EntryControlplaneConfig): Promise<ChannelInitGrant>;
-export {};

package/dist/browser/controlplane.js

@@ -1,23 +1,6 @@
 import { assertChannelInitGrant } from "../facade.js";
-export class ControlplaneRequestError extends Error {
-    status;
-    code;
-    responseBody;
-    constructor(args) {
-        super(args.message);
-        this.name = "ControlplaneRequestError";
-        this.status = args.status;
-        this.code = String(args.code ?? "").trim();
-        this.responseBody = args.responseBody;
-    }
-}
-function resolveFetch(fetchImpl) {
-    if (fetchImpl)
-        return fetchImpl;
-    if (typeof globalThis.fetch === "function")
-        return globalThis.fetch.bind(globalThis);
-    throw new Error("global fetch is not available");
-}
+import { requestControlplaneJSON, } from "../controlplane/request.js";
+export { ControlplaneRequestError, requestConnectArtifact, requestEntryConnectArtifact, } from "../controlplane/request.js";
 function buildURL(baseUrl, path) {
     const base = String(baseUrl ?? "").trim();
     if (base === "")
@@ -37,63 +20,25 @@ function buildPayload(endpointId, payload) {
     return out;
 }
 async function requestGrant(url, init) {
-    const runFetch = resolveFetch(init.fetch);
-    const response = await runFetch(url, {
-        ...init,
-        cache: "no-store",
-    });
-    if (!response.ok) {
-        const rawBody = await response.text();
-        const bodyText = String(rawBody ?? "").trim();
-        let responseBody = bodyText;
-        if (bodyText !== "") {
-            try {
-                responseBody = JSON.parse(bodyText);
-            }
-            catch {
-                responseBody = bodyText;
-            }
-        }
-        let message = `Failed to get channel grant: ${response.status}`;
-        let code = "";
-        if (responseBody && typeof responseBody === "object") {
-            const error = responseBody.error;
-            if (error && typeof error === "object") {
-                const nextMessage = String(error.message ?? "").trim();
-                if (nextMessage !== "") {
-                    message = nextMessage;
-                }
-                code = String(error.code ?? "").trim();
-            }
-        }
-        else if (typeof responseBody === "string" && responseBody !== "") {
-            message = responseBody;
-        }
-        throw new ControlplaneRequestError({
-            status: response.status,
-            message,
-            code,
-            responseBody,
-        });
-    }
-    const data = (await response.json());
-    if (!data?.grant_client) {
-        throw new Error("Invalid controlplane response: missing `grant_client`");
-    }
-    return assertChannelInitGrant(data.grant_client);
+    return await requestControlplaneJSON(url, init);
 }
 export async function requestChannelGrant(config) {
     const headers = new Headers(config.headers);
     if (!headers.has("Content-Type")) {
         headers.set("Content-Type", "application/json");
     }
-    return await requestGrant(buildURL(config.baseUrl, "/v1/channel/init"), {
+    const data = (await requestGrant(buildURL(config.baseUrl, "/v1/channel/init"), {
         ...(config.fetch === undefined ? {} : { fetch: config.fetch }),
         method: "POST",
         credentials: config.credentials ?? "omit",
         headers,
         body: JSON.stringify(buildPayload(config.endpointId, config.payload)),
-    });
+        ...(config.signal === undefined ? {} : { signal: config.signal }),
+    }));
+    if (!data?.grant_client) {
+        throw new Error("Invalid controlplane response: missing `grant_client`");
+    }
+    return assertChannelInitGrant(data.grant_client);
 }
 export async function requestEntryChannelGrant(config) {
     const entryTicket = String(config.entryTicket ?? "").trim();
@@ -105,11 +50,16 @@ export async function requestEntryChannelGrant(config) {
     if (!headers.has("Content-Type")) {
         headers.set("Content-Type", "application/json");
     }
-    return await requestGrant(buildURL(config.baseUrl, `/v1/channel/init/entry?endpoint_id=${encodeURIComponent(endpointId)}`), {
+    const data = (await requestGrant(buildURL(config.baseUrl, `/v1/channel/init/entry?endpoint_id=${encodeURIComponent(endpointId)}`), {
         ...(config.fetch === undefined ? {} : { fetch: config.fetch }),
         method: "POST",
         credentials: config.credentials ?? "omit",
         headers,
         body: JSON.stringify(buildPayload(endpointId, config.payload)),
-    });
+        ...(config.signal === undefined ? {} : { signal: config.signal }),
+    }));
+    if (!data?.grant_client) {
+        throw new Error("Invalid controlplane response: missing `grant_client`");
+    }
+    return assertChannelInitGrant(data.grant_client);
 }

package/dist/browser/index.d.ts

@@ -1,6 +1,8 @@
 export type { ConnectBrowserOptions, DirectConnectBrowserOptions, TunnelConnectBrowserOptions } from "./connect.js";
 export { connectBrowser, connectDirectBrowser, connectTunnelBrowser } from "./connect.js";
-export type { ControlplaneConfig, EntryControlplaneConfig } from "./controlplane.js";
-export { ControlplaneRequestError, requestChannelGrant, requestEntryChannelGrant } from "./controlplane.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";
+export { ControlplaneRequestError, requestChannelGrant, requestConnectArtifact, requestEntryChannelGrant, requestEntryConnectArtifact, } from "./controlplane.js";
 export type { BrowserReconnectConfig, DirectBrowserReconnectConfig, TunnelBrowserReconnectConfig, } from "./reconnectConfig.js";
 export { createBrowserReconnectConfig, createDirectBrowserReconnectConfig, createTunnelBrowserReconnectConfig, } from "./reconnectConfig.js";

package/dist/browser/index.js

@@ -1,3 +1,4 @@
 export { connectBrowser, connectDirectBrowser, connectTunnelBrowser } from "./connect.js";
-export { ControlplaneRequestError, requestChannelGrant, requestEntryChannelGrant } from "./controlplane.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/browser/reconnectConfig.d.ts

@@ -1,7 +1,10 @@
+import type { ConnectArtifact } from "../connect/artifact.js";
 import type { ChannelInitGrant } from "../gen/flowersec/controlplane/v1.gen.js";
 import type { DirectConnectInfo } from "../gen/flowersec/direct/v1.gen.js";
 import type { ClientObserverLike } from "../observability/observer.js";
 import type { AutoReconnectConfig, ConnectConfig as ReconnectConnectConfig } from "../reconnect/index.js";
+import { type ArtifactAwareReconnectConfig, type ArtifactFactoryArgs } from "../reconnect/artifactControlplane.js";
+import type { RequestConnectArtifactInput, RequestEntryConnectArtifactInput } from "../controlplane/index.js";
 import type { DirectConnectBrowserOptions, TunnelConnectBrowserOptions } from "./connect.js";
 import { type ControlplaneConfig } from "./controlplane.js";
 type SharedReconnectOptions = Readonly<{
@@ -10,14 +13,24 @@ type SharedReconnectOptions = Readonly<{
 }>;
 type TunnelReconnectConnectOptions = Omit<TunnelConnectBrowserOptions, "observer" | "signal">;
 type DirectReconnectConnectOptions = Omit<DirectConnectBrowserOptions, "observer" | "signal">;
-export type TunnelBrowserReconnectConfig = SharedReconnectOptions & Readonly<{
+type ArtifactAwareTunnelReconnectConfig = ArtifactAwareReconnectConfig & Readonly<{
+    artifact?: ConnectArtifact;
+    getArtifact?: (args: ArtifactFactoryArgs) => Promise<ConnectArtifact>;
+    artifactControlplane?: RequestConnectArtifactInput | RequestEntryConnectArtifactInput;
+}>;
+type ArtifactAwareDirectReconnectConfig = ArtifactAwareReconnectConfig & Readonly<{
+    artifact?: ConnectArtifact;
+    getArtifact?: (args: ArtifactFactoryArgs) => Promise<ConnectArtifact>;
+    artifactControlplane?: RequestConnectArtifactInput | RequestEntryConnectArtifactInput;
+}>;
+export type TunnelBrowserReconnectConfig = SharedReconnectOptions & ArtifactAwareTunnelReconnectConfig & Readonly<{
     mode?: "tunnel";
     connect?: TunnelReconnectConnectOptions;
     grant?: ChannelInitGrant;
     getGrant?: () => Promise<ChannelInitGrant>;
     controlplane?: ControlplaneConfig;
 }>;
-export type DirectBrowserReconnectConfig = SharedReconnectOptions & Readonly<{
+export type DirectBrowserReconnectConfig = SharedReconnectOptions & ArtifactAwareDirectReconnectConfig & Readonly<{
     mode: "direct";
     connect?: DirectReconnectConnectOptions;
     directInfo?: DirectConnectInfo;

package/dist/browser/reconnectConfig.js

@@ -1,5 +1,6 @@
-import { connectDirectBrowser, connectTunnelBrowser } from "./connect.js";
-import { requestChannelGrant } from "./controlplane.js";
+import { resolveConnectArtifact, updateTraceId, } from "../reconnect/artifactControlplane.js";
+import { connectBrowser, connectDirectBrowser, connectTunnelBrowser } from "./connect.js";
+import { requestChannelGrant, } from "./controlplane.js";
 async function resolveTunnelGrant(config) {
     if (config.getGrant)
         return await config.getGrant();
@@ -17,25 +18,55 @@ async function resolveDirectInfo(config) {
     throw new Error("Direct reconnect config requires `getDirectInfo` or `directInfo`");
 }
 export function createTunnelBrowserReconnectConfig(config) {
+    let traceId = config.artifact?.correlation?.trace_id;
     return {
         ...(config.observer === undefined ? {} : { observer: config.observer }),
         ...(config.autoReconnect === undefined ? {} : { autoReconnect: config.autoReconnect }),
-        connectOnce: async ({ signal, observer }) => await connectTunnelBrowser(await resolveTunnelGrant(config), {
-            ...(config.connect ?? {}),
-            signal,
-            observer,
-        }),
+        connectOnce: async ({ signal, observer }) => {
+            if (config.getArtifact || config.artifact || config.artifactControlplane) {
+                const artifact = await resolveConnectArtifact(config, traceId, signal);
+                if (artifact.transport !== "tunnel") {
+                    throw new Error("Tunnel reconnect config requires a tunnel ConnectArtifact");
+                }
+                traceId = updateTraceId(traceId, artifact);
+                return await connectBrowser(artifact, {
+                    ...(config.connect ?? {}),
+                    signal,
+                    observer,
+                });
+            }
+            return await connectTunnelBrowser(await resolveTunnelGrant(config), {
+                ...(config.connect ?? {}),
+                signal,
+                observer,
+            });
+        },
     };
 }
 export function createDirectBrowserReconnectConfig(config) {
+    let traceId = config.artifact?.correlation?.trace_id;
     return {
         ...(config.observer === undefined ? {} : { observer: config.observer }),
         ...(config.autoReconnect === undefined ? {} : { autoReconnect: config.autoReconnect }),
-        connectOnce: async ({ signal, observer }) => await connectDirectBrowser(await resolveDirectInfo(config), {
-            ...(config.connect ?? {}),
-            signal,
-            observer,
-        }),
+        connectOnce: async ({ signal, observer }) => {
+            if (config.getArtifact || config.artifact || config.artifactControlplane) {
+                const artifact = await resolveConnectArtifact(config, traceId, signal);
+                if (artifact.transport !== "direct") {
+                    throw new Error("Direct reconnect config requires a direct ConnectArtifact");
+                }
+                traceId = updateTraceId(traceId, artifact);
+                return await connectBrowser(artifact, {
+                    ...(config.connect ?? {}),
+                    signal,
+                    observer,
+                });
+            }
+            return await connectDirectBrowser(await resolveDirectInfo(config), {
+                ...(config.connect ?? {}),
+                signal,
+                observer,
+            });
+        },
     };
 }
 export function createBrowserReconnectConfig(config) {

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

@@ -1,6 +1,7 @@
 import { type ClientObserverLike } from "../observability/observer.js";
 import { type WebSocketLike } from "../ws-client/binaryTransport.js";
 import type { ClientInternal } from "../client.js";
+import type { ConnectScopeResolverMap } from "../connect/internalNormalize.js";
 export type ConnectOptionsBase = Readonly<{
     /** Explicit Origin value (required). In browsers this must match window.location.origin. */
     origin: string;
@@ -24,6 +25,10 @@ export type ConnectOptionsBase = Readonly<{
     wsFactory?: (url: string, origin: string) => WebSocketLike;
     /** Optional observer for client metrics. */
     observer?: ClientObserverLike;
+    /** Experimental scope validators keyed by scope name. */
+    scopeResolvers?: ConnectScopeResolverMap;
+    /** Experimental migration switch for optional scope failures. */
+    relaxedOptionalScopeValidation?: boolean;
     /** Encrypted keepalive ping interval in milliseconds (0 disables). */
     keepaliveIntervalMs?: number;
 }>;

package/dist/client-connect/connectCore.js

@@ -11,7 +11,7 @@ import { OriginMismatchError, WsFactoryRequiredError, classifyConnectError, clas
 import { prepareChannelId } from "./contract.js";
 import { isTunnelAttachCloseReason } from "./tunnelAttachCloseReason.js";
 export async function connectCore(args) {
-    const observer = normalizeObserver(args.opts.observer);
+    const observer = normalizeObserver(args.opts.observer, { path: args.path });
     const signal = args.opts.signal;
     const connectStart = nowSeconds();
     let attachState = args.path === "tunnel" ? "not_started" : "accepted";

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

@@ -1,3 +1,3 @@
-export declare const tunnelAttachCloseReasons: readonly ["too_many_connections", "expected_attach", "invalid_attach", "invalid_token", "channel_mismatch", "init_exp_mismatch", "idle_timeout_mismatch", "role_mismatch", "token_replay", "replace_rate_limited", "attach_failed", "timeout", "canceled"];
+export declare const tunnelAttachCloseReasons: readonly ["too_many_connections", "expected_attach", "invalid_attach", "invalid_token", "channel_mismatch", "init_exp_mismatch", "idle_timeout_mismatch", "role_mismatch", "token_replay", "tenant_mismatch", "policy_denied", "policy_error", "replace_rate_limited", "attach_failed", "timeout", "canceled"];
 export type TunnelAttachCloseReason = (typeof tunnelAttachCloseReasons)[number];
 export declare function isTunnelAttachCloseReason(v: string | undefined): v is TunnelAttachCloseReason;

package/dist/client-connect/tunnelAttachCloseReason.js

@@ -8,10 +8,13 @@ export const tunnelAttachCloseReasons = [
     "idle_timeout_mismatch",
     "role_mismatch",
     "token_replay",
+    "tenant_mismatch",
+    "policy_denied",
+    "policy_error",
     "replace_rate_limited",
     "attach_failed",
     "timeout",
-    "canceled"
+    "canceled",
 ];
 export function isTunnelAttachCloseReason(v) {
     if (v == null)

package/dist/connect/artifact.d.ts

@@ -0,0 +1,37 @@
+import { type ChannelInitGrant } from "../gen/flowersec/controlplane/v1.gen.js";
+import { type DirectConnectInfo } from "../gen/flowersec/direct/v1.gen.js";
+export type ConnectArtifactTransport = "tunnel" | "direct";
+export type CorrelationKV = Readonly<{
+    key: string;
+    value: string;
+}>;
+export type CorrelationContext = Readonly<{
+    v: 1;
+    trace_id?: string;
+    session_id?: string;
+    tags: readonly CorrelationKV[];
+}>;
+export type ScopePayload = Record<string, unknown>;
+export type ScopeMetadataEntry = Readonly<{
+    scope: string;
+    scope_version: number;
+    critical: boolean;
+    payload: ScopePayload;
+}>;
+export type TunnelClientConnectArtifact = Readonly<{
+    v: 1;
+    transport: "tunnel";
+    tunnel_grant: ChannelInitGrant;
+    scoped?: readonly ScopeMetadataEntry[];
+    correlation?: CorrelationContext;
+}>;
+export type DirectClientConnectArtifact = Readonly<{
+    v: 1;
+    transport: "direct";
+    direct_info: DirectConnectInfo;
+    scoped?: readonly ScopeMetadataEntry[];
+    correlation?: CorrelationContext;
+}>;
+export type ConnectArtifact = TunnelClientConnectArtifact | DirectClientConnectArtifact;
+export declare function hasArtifactOnlyFields(value: Record<string, unknown>): boolean;
+export declare function assertConnectArtifact(value: unknown): ConnectArtifact;

package/dist/connect/artifact.js

@@ -0,0 +1,217 @@
+import { assertChannelInitGrant, Role as ControlRole } from "../gen/flowersec/controlplane/v1.gen.js";
+import { assertDirectConnectInfo } from "../gen/flowersec/direct/v1.gen.js";
+const SCOPE_NAME_RE = /^[a-z][a-z0-9._-]{0,63}$/;
+const TAG_KEY_RE = /^[a-z][a-z0-9._-]{0,31}$/;
+const CORRELATION_ID_RE = /^[A-Za-z0-9._~-]{8,128}$/;
+const encoder = new TextEncoder();
+const TUNNEL_ARTIFACT_KEYS = new Set(["v", "transport", "tunnel_grant", "scoped", "correlation"]);
+const DIRECT_ARTIFACT_KEYS = new Set(["v", "transport", "direct_info", "scoped", "correlation"]);
+const ARTIFACT_ONLY_KEYS = new Set(["v", "transport", "tunnel_grant", "direct_info", "scoped", "correlation"]);
+function isRecord(v) {
+    return typeof v === "object" && v != null && !Array.isArray(v);
+}
+function hasOwn(o, key) {
+    return Object.prototype.hasOwnProperty.call(o, key);
+}
+function assertNoUnknownFields(kind, obj, allowed) {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.has(key))
+            throw new Error(`bad ${kind}.${key}`);
+    }
+}
+function assertPositiveInt(name, value, min, max) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value))
+        throw new Error(`bad ${name}`);
+    if (value < min || value > max)
+        throw new Error(`bad ${name}`);
+    return value;
+}
+function utf8Len(value) {
+    return encoder.encode(value).length;
+}
+function normalizedJSONForSize(value) {
+    return serializeNormalizedJSON(normalizeJSONValue(value));
+}
+function normalizeJSONValue(value) {
+    if (value === null)
+        return null;
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return value;
+        case "number":
+            if (!Number.isFinite(value))
+                throw new Error("bad payload.number");
+            return value;
+        case "object": {
+            if (Array.isArray(value)) {
+                return value.map((entry) => normalizeJSONValue(entry));
+            }
+            if (!isRecord(value))
+                throw new Error("bad payload.object");
+            const out = {};
+            for (const key of Object.keys(value).sort()) {
+                out[key] = normalizeJSONValue(value[key]);
+            }
+            return out;
+        }
+        default:
+            throw new Error("bad payload.value");
+    }
+}
+function serializeNormalizedJSON(value) {
+    return JSON.stringify(value);
+}
+function maxContainerDepth(value) {
+    if (Array.isArray(value)) {
+        let best = 1;
+        for (const entry of value)
+            best = Math.max(best, 1 + maxContainerDepth(entry));
+        return best;
+    }
+    if (isRecord(value)) {
+        let best = 1;
+        for (const entry of Object.values(value))
+            best = Math.max(best, 1 + maxContainerDepth(entry));
+        return best;
+    }
+    return 0;
+}
+function sanitizeCorrelationID(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    if (!CORRELATION_ID_RE.test(trimmed))
+        return undefined;
+    return trimmed;
+}
+function assertCorrelationKV(value) {
+    if (!isRecord(value))
+        throw new Error("bad CorrelationKV");
+    assertNoUnknownFields("CorrelationKV", value, new Set(["key", "value"]));
+    if (typeof value.key !== "string" || !TAG_KEY_RE.test(value.key))
+        throw new Error("bad CorrelationKV.key");
+    if (typeof value.value !== "string")
+        throw new Error("bad CorrelationKV.value");
+    if (utf8Len(value.key) > 32)
+        throw new Error("bad CorrelationKV.key");
+    if (utf8Len(value.value) > 128)
+        throw new Error("bad CorrelationKV.value");
+    return Object.freeze({ key: value.key, value: value.value });
+}
+function assertCorrelationContext(value) {
+    if (!isRecord(value))
+        throw new Error("bad CorrelationContext");
+    assertNoUnknownFields("CorrelationContext", value, new Set(["v", "trace_id", "session_id", "tags"]));
+    if (value.v !== 1)
+        throw new Error("bad CorrelationContext.v");
+    const rawTags = value.tags;
+    if (rawTags !== undefined && !Array.isArray(rawTags))
+        throw new Error("bad CorrelationContext.tags");
+    const tags = (rawTags ?? []).map((entry) => assertCorrelationKV(entry));
+    const seen = new Set();
+    for (const tag of tags) {
+        if (seen.has(tag.key))
+            throw new Error("bad CorrelationContext.tags");
+        seen.add(tag.key);
+    }
+    if (tags.length > 8)
+        throw new Error("bad CorrelationContext.tags");
+    const traceId = sanitizeCorrelationID(value.trace_id);
+    const sessionId = sanitizeCorrelationID(value.session_id);
+    return Object.freeze({
+        v: 1,
+        ...(traceId === undefined ? {} : { trace_id: traceId }),
+        ...(sessionId === undefined ? {} : { session_id: sessionId }),
+        tags: Object.freeze(tags),
+    });
+}
+function assertPayloadObject(value) {
+    if (!isRecord(value))
+        throw new Error("bad ScopeMetadataEntry.payload");
+    const normalized = normalizedJSONForSize(value);
+    if (utf8Len(normalized) > 8192)
+        throw new Error("bad ScopeMetadataEntry.payload");
+    if (maxContainerDepth(value) > 8)
+        throw new Error("bad ScopeMetadataEntry.payload");
+    return value;
+}
+function assertScopeMetadataEntry(value) {
+    if (!isRecord(value))
+        throw new Error("bad ScopeMetadataEntry");
+    assertNoUnknownFields("ScopeMetadataEntry", value, new Set(["scope", "scope_version", "critical", "payload"]));
+    if (typeof value.scope !== "string" || !SCOPE_NAME_RE.test(value.scope))
+        throw new Error("bad ScopeMetadataEntry.scope");
+    if (typeof value.critical !== "boolean")
+        throw new Error("bad ScopeMetadataEntry.critical");
+    const scopeVersion = assertPositiveInt("ScopeMetadataEntry.scope_version", value.scope_version, 1, 65535);
+    const payload = assertPayloadObject(value.payload);
+    return Object.freeze({
+        scope: value.scope,
+        scope_version: scopeVersion,
+        critical: value.critical,
+        payload,
+    });
+}
+function assertScopedEntries(value) {
+    if (!Array.isArray(value))
+        throw new Error("bad ConnectArtifact.scoped");
+    if (value.length > 8)
+        throw new Error("bad ConnectArtifact.scoped");
+    const out = value.map((entry) => assertScopeMetadataEntry(entry));
+    const seen = new Set();
+    for (const entry of out) {
+        if (seen.has(entry.scope))
+            throw new Error("bad ConnectArtifact.scoped");
+        seen.add(entry.scope);
+    }
+    return Object.freeze(out);
+}
+function assertArtifactObject(value) {
+    if (!isRecord(value))
+        throw new Error("bad ConnectArtifact");
+    return value;
+}
+function assertArtifactTransport(value) {
+    if (value !== "tunnel" && value !== "direct")
+        throw new Error("bad ConnectArtifact.transport");
+    return value;
+}
+export function hasArtifactOnlyFields(value) {
+    return Object.keys(value).some((key) => ARTIFACT_ONLY_KEYS.has(key));
+}
+export function assertConnectArtifact(value) {
+    const record = assertArtifactObject(value);
+    if (record.v !== 1)
+        throw new Error("bad ConnectArtifact.v");
+    const transport = assertArtifactTransport(record.transport);
+    const scoped = record.scoped === undefined ? undefined : assertScopedEntries(record.scoped);
+    const correlation = record.correlation === undefined ? undefined : assertCorrelationContext(record.correlation);
+    if (transport === "tunnel") {
+        assertNoUnknownFields("TunnelClientConnectArtifact", record, TUNNEL_ARTIFACT_KEYS);
+        if (!hasOwn(record, "tunnel_grant"))
+            throw new Error("bad TunnelClientConnectArtifact.tunnel_grant");
+        const tunnelGrant = assertChannelInitGrant(record.tunnel_grant);
+        if (tunnelGrant.role !== ControlRole.Role_client) {
+            throw new Error("bad TunnelClientConnectArtifact.tunnel_grant.role");
+        }
+        return Object.freeze({
+            v: 1,
+            transport,
+            tunnel_grant: tunnelGrant,
+            ...(scoped === undefined ? {} : { scoped }),
+            ...(correlation === undefined ? {} : { correlation }),
+        });
+    }
+    assertNoUnknownFields("DirectClientConnectArtifact", record, DIRECT_ARTIFACT_KEYS);
+    if (!hasOwn(record, "direct_info"))
+        throw new Error("bad DirectClientConnectArtifact.direct_info");
+    const directInfo = assertDirectConnectInfo(record.direct_info);
+    return Object.freeze({
+        v: 1,
+        transport,
+        direct_info: directInfo,
+        ...(scoped === undefined ? {} : { scoped }),
+        ...(correlation === undefined ? {} : { correlation }),
+    });
+}