@floegence/flowersec-core 0.17.2 → 0.18.0

package/README.md

@@ -15,10 +15,13 @@ npm install @floegence/flowersec-core
 Browser (recommended):
 
 ```ts
-import { connectBrowser } from "@floegence/flowersec-core/browser";
+import { connectBrowser, requestConnectArtifact } from "@floegence/flowersec-core/browser";
 
-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();
 ```
@@ -28,8 +31,15 @@ Node.js (recommended):
 ```ts
 import { connectNode } from "@floegence/flowersec-core/node";
 
-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 artifactEnvelope = await fetch("https://your-app.example/api/flowersec/connect/artifact", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ endpoint_id: "env_demo" }),
+}).then((r) => r.json());
+
+const client = await connectNode(artifactEnvelope.connect_artifact, {
+  origin: "https://your-app.example",
+});
 await client.ping();
 client.close();
 ```

package/dist/browser/controlplane.d.ts

@@ -1,4 +1,5 @@
 import { type ChannelInitGrant } from "../facade.js";
+import { type ConnectArtifact } from "../connect/artifact.js";
 type FetchLike = typeof fetch;
 type BaseControlplaneRequestConfig = Readonly<{
     baseUrl?: string;
@@ -12,6 +13,15 @@ export type ControlplaneConfig = BaseControlplaneRequestConfig;
 export type EntryControlplaneConfig = BaseControlplaneRequestConfig & Readonly<{
     entryTicket: string;
 }>;
+export type ConnectArtifactRequestConfig = BaseControlplaneRequestConfig & Readonly<{
+    path?: string;
+    correlation?: Readonly<{
+        traceId?: string;
+    }>;
+}>;
+export type EntryConnectArtifactRequestConfig = ConnectArtifactRequestConfig & Readonly<{
+    entryTicket: string;
+}>;
 export declare class ControlplaneRequestError extends Error {
     readonly status: number;
     readonly code: string;
@@ -25,4 +35,6 @@ export declare class ControlplaneRequestError extends Error {
 }
 export declare function requestChannelGrant(config: ControlplaneConfig): Promise<ChannelInitGrant>;
 export declare function requestEntryChannelGrant(config: EntryControlplaneConfig): Promise<ChannelInitGrant>;
+export declare function requestConnectArtifact(config: ConnectArtifactRequestConfig): Promise<ConnectArtifact>;
+export declare function requestEntryConnectArtifact(config: EntryConnectArtifactRequestConfig): Promise<ConnectArtifact>;
 export {};

package/dist/browser/controlplane.js

@@ -1,4 +1,5 @@
 import { assertChannelInitGrant } from "../facade.js";
+import { assertConnectArtifact } from "../connect/artifact.js";
 export class ControlplaneRequestError extends Error {
     status;
     code;
@@ -76,24 +77,24 @@ async function requestGrant(url, init) {
             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 response.json();
 }
 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)),
-    });
+    }));
+    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 +106,67 @@ 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)),
-    });
+    }));
+    if (!data?.grant_client) {
+        throw new Error("Invalid controlplane response: missing `grant_client`");
+    }
+    return assertChannelInitGrant(data.grant_client);
+}
+function buildConnectArtifactPayload(config) {
+    const body = {
+        endpoint_id: String(config.endpointId ?? "").trim(),
+    };
+    if (body.endpoint_id === "")
+        throw new Error("endpointId is required");
+    if (config.payload !== undefined)
+        body.payload = { ...config.payload };
+    const traceId = String(config.correlation?.traceId ?? "").trim();
+    if (traceId !== "") {
+        body.correlation = { trace_id: traceId };
+    }
+    return body;
+}
+export async function requestConnectArtifact(config) {
+    const headers = new Headers(config.headers);
+    if (!headers.has("Content-Type")) {
+        headers.set("Content-Type", "application/json");
+    }
+    const data = (await requestGrant(buildURL(config.baseUrl, config.path ?? "/v1/connect/artifact"), {
+        ...(config.fetch === undefined ? {} : { fetch: config.fetch }),
+        method: "POST",
+        credentials: config.credentials ?? "omit",
+        headers,
+        body: JSON.stringify(buildConnectArtifactPayload(config)),
+    }));
+    if (!data?.connect_artifact) {
+        throw new Error("Invalid controlplane response: missing `connect_artifact`");
+    }
+    return assertConnectArtifact(data.connect_artifact);
+}
+export async function requestEntryConnectArtifact(config) {
+    const entryTicket = String(config.entryTicket ?? "").trim();
+    if (entryTicket === "")
+        throw new Error("entryTicket is required");
+    const headers = new Headers(config.headers);
+    headers.set("Authorization", `Bearer ${entryTicket}`);
+    if (!headers.has("Content-Type")) {
+        headers.set("Content-Type", "application/json");
+    }
+    const data = (await requestGrant(buildURL(config.baseUrl, config.path ?? "/v1/connect/artifact/entry"), {
+        ...(config.fetch === undefined ? {} : { fetch: config.fetch }),
+        method: "POST",
+        credentials: config.credentials ?? "omit",
+        headers,
+        body: JSON.stringify(buildConnectArtifactPayload(config)),
+    }));
+    if (!data?.connect_artifact) {
+        throw new Error("Invalid controlplane response: missing `connect_artifact`");
+    }
+    return assertConnectArtifact(data.connect_artifact);
 }

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,23 +1,37 @@
+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 { DirectConnectBrowserOptions, TunnelConnectBrowserOptions } from "./connect.js";
-import { type ControlplaneConfig } from "./controlplane.js";
+import { type ConnectArtifactRequestConfig, type ControlplaneConfig, type EntryConnectArtifactRequestConfig } from "./controlplane.js";
 type SharedReconnectOptions = Readonly<{
     observer?: ClientObserverLike;
     autoReconnect?: AutoReconnectConfig;
 }>;
+type ArtifactFactoryArgs = Readonly<{
+    traceId?: string;
+}>;
 type TunnelReconnectConnectOptions = Omit<TunnelConnectBrowserOptions, "observer" | "signal">;
 type DirectReconnectConnectOptions = Omit<DirectConnectBrowserOptions, "observer" | "signal">;
-export type TunnelBrowserReconnectConfig = SharedReconnectOptions & Readonly<{
+type ArtifactAwareTunnelReconnectConfig = Readonly<{
+    artifact?: ConnectArtifact;
+    getArtifact?: (args: ArtifactFactoryArgs) => Promise<ConnectArtifact>;
+    artifactControlplane?: ConnectArtifactRequestConfig | EntryConnectArtifactRequestConfig;
+}>;
+type ArtifactAwareDirectReconnectConfig = Readonly<{
+    artifact?: ConnectArtifact;
+    getArtifact?: (args: ArtifactFactoryArgs) => Promise<ConnectArtifact>;
+    artifactControlplane?: ConnectArtifactRequestConfig | EntryConnectArtifactRequestConfig;
+}>;
+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,5 @@
-import { connectDirectBrowser, connectTunnelBrowser } from "./connect.js";
-import { requestChannelGrant } from "./controlplane.js";
+import { connectBrowser, connectDirectBrowser, connectTunnelBrowser } from "./connect.js";
+import { requestChannelGrant, requestConnectArtifact, requestEntryConnectArtifact, } from "./controlplane.js";
 async function resolveTunnelGrant(config) {
     if (config.getGrant)
         return await config.getGrant();
@@ -16,26 +16,82 @@ async function resolveDirectInfo(config) {
         return config.directInfo;
     throw new Error("Direct reconnect config requires `getDirectInfo` or `directInfo`");
 }
+async function resolveConnectArtifact(config, traceId) {
+    if (config.getArtifact) {
+        return await config.getArtifact(traceId === undefined ? {} : { traceId });
+    }
+    if (config.artifact)
+        return config.artifact;
+    if (config.artifactControlplane) {
+        const correlation = traceId === undefined
+            ? config.artifactControlplane.correlation
+            : { traceId };
+        if ("entryTicket" in config.artifactControlplane) {
+            return await requestEntryConnectArtifact({
+                ...config.artifactControlplane,
+                ...(correlation === undefined ? {} : { correlation }),
+            });
+        }
+        return await requestConnectArtifact({
+            ...config.artifactControlplane,
+            ...(correlation === undefined ? {} : { correlation }),
+        });
+    }
+    throw new Error("Artifact reconnect config requires `getArtifact`, `artifact`, or `artifactControlplane`");
+}
+function updateTraceId(current, artifact) {
+    return artifact.correlation?.trace_id ?? current;
+}
 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);
+                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);
+                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/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 }),
+    });
+}

package/dist/connect/internalNormalize.d.ts

@@ -0,0 +1,22 @@
+import { type ClientObserverLike } from "../observability/observer.js";
+import { type CorrelationContext, type ScopeMetadataEntry } from "./artifact.js";
+export type ConnectScopeResolver = (entry: ScopeMetadataEntry) => void | Promise<void>;
+export type ConnectScopeResolverMap = Readonly<Record<string, ConnectScopeResolver>>;
+type NormalizeOptions = Readonly<{
+    observer?: ClientObserverLike;
+    scopeResolvers?: ConnectScopeResolverMap;
+    relaxedOptionalScopeValidation?: boolean;
+}>;
+export type NormalizedConnectInput = Readonly<{
+    kind: "tunnel";
+    input: unknown;
+    correlation?: CorrelationContext;
+    observer?: ClientObserverLike;
+}> | Readonly<{
+    kind: "direct";
+    input: unknown;
+    correlation?: CorrelationContext;
+    observer?: ClientObserverLike;
+}>;
+export declare function normalizeConnectInput(input: unknown, opts?: NormalizeOptions): Promise<NormalizedConnectInput>;
+export {};