@floegence/flowersec-core 2.5.3 → 3.0.0

package/dist/v3/capability.js

@@ -0,0 +1,345 @@
+import { sha256 } from "@noble/hashes/sha2.js";
+import { concatBytes, u32be } from "../utils/bin.js";
+import { canonicalizeJCSV3 } from "./jcs.js";
+import { preflightJSONV3 } from "./jsonPreflight.js";
+import { FLOWERSEC_V3_CRYPTO_LABELS } from "./transportConstants.js";
+const encoder = new TextEncoder();
+const carriers = Object.freeze(["raw_quic", "websocket", "webtransport"]);
+const token = /^[a-z][a-z0-9_]{0,127}$/;
+const identities = new Set([
+    "go/native",
+    "rust/native",
+    "swift/ios",
+    "swift/linux",
+    "swift/macos",
+    "typescript/browser",
+    "typescript/node",
+]);
+const reasons = new Set([
+    "adapter_not_composed",
+    "browser_no_raw_udp",
+    "browser_websocket_api_unavailable",
+    "browser_webtransport_api_unavailable",
+    "driver_unavailable",
+    "node_native_transport_unavailable",
+    "node_webtransport_driver_unavailable",
+    "swift_apple_client_profile_excludes_raw_quic",
+    "swift_apple_client_profile_excludes_webtransport",
+    "websocket_adapter_not_supported_on_linux",
+]);
+export function defineRuntimeCapabilityDescriptorV3(runtime, tuples, unsupported) {
+    const descriptor = freezeDescriptor({
+        language: "typescript",
+        runtime,
+        schemaVersion: 3,
+        tuples,
+        unsupported,
+    });
+    validateRuntimeCapabilityDescriptorV3(descriptor);
+    return descriptor;
+}
+export function encodeRuntimeCapabilityDescriptorV3(descriptor) {
+    validateRuntimeCapabilityDescriptorV3(descriptor);
+    return canonicalizeJCSV3(descriptor);
+}
+export function decodeRuntimeCapabilityDescriptorV3(raw) {
+    let text;
+    try {
+        text = typeof raw === "string" ? raw : new TextDecoder("utf-8", { fatal: true }).decode(raw);
+    }
+    catch {
+        throw new TypeError("runtime capability descriptor is not UTF-8");
+    }
+    let parsed;
+    try {
+        preflightJSONV3(text);
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new TypeError("invalid runtime capability JSON");
+    }
+    const descriptor = decodeDescriptor(parsed);
+    if (encodeRuntimeCapabilityDescriptorV3(descriptor) !== text) {
+        throw new TypeError("runtime capability descriptor is not canonical JCS");
+    }
+    return descriptor;
+}
+export function runtimeCapabilityDigestV3(descriptor) {
+    const canonical = encoder.encode(encodeRuntimeCapabilityDescriptorV3(descriptor));
+    return sha256(concatBytes([
+        encoder.encode(FLOWERSEC_V3_CRYPTO_LABELS["runtime-capability"]),
+        u32be(canonical.length),
+        canonical,
+    ]));
+}
+export function runtimeCapabilityDigestHexV3(descriptor) {
+    return Array.from(runtimeCapabilityDigestV3(descriptor), (value) => value.toString(16).padStart(2, "0")).join("");
+}
+export function supportsCandidateSecurityV3(descriptor, carrier, path, sessionRole, mode) {
+    validateRuntimeCapabilityDescriptorV3(descriptor);
+    return descriptor.tuples.some((tuple) => tuple.carrier === carrier && tuple.networkMode === "dial" && tuple.path === path &&
+        tuple.sessionRole === sessionRole && tuple.securityModes.includes(mode));
+}
+export function validateRuntimeCapabilityDescriptorV3(descriptor) {
+    if (descriptor.schemaVersion !== 3 || !token.test(descriptor.language) || !token.test(descriptor.runtime) ||
+        !identities.has(`${descriptor.language}/${descriptor.runtime}`)) {
+        throw new TypeError("invalid runtime capability descriptor identity");
+    }
+    const supported = new Set();
+    let previousTuple;
+    for (const tuple of descriptor.tuples) {
+        validateTuple(tuple);
+        if (previousTuple !== undefined && compareTuple(previousTuple, tuple) >= 0) {
+            throw new TypeError("runtime capability tuples must be unique and canonically sorted");
+        }
+        supported.add(tuple.carrier);
+        previousTuple = tuple;
+    }
+    const unavailable = new Set();
+    let previousUnsupported;
+    for (const item of descriptor.unsupported) {
+        if (!carriers.includes(item.carrier) || !reasons.has(item.reason) || supported.has(item.carrier)) {
+            throw new TypeError("invalid unsupported runtime carrier");
+        }
+        if (previousUnsupported !== undefined && compareASCII(previousUnsupported.carrier, item.carrier) >= 0) {
+            throw new TypeError("unsupported runtime carriers must be unique and canonically sorted");
+        }
+        unavailable.add(item.carrier);
+        previousUnsupported = item;
+    }
+    for (const carrier of carriers) {
+        if (supported.has(carrier) === unavailable.has(carrier)) {
+            throw new TypeError(`runtime capability must support or explicitly reject ${carrier}`);
+        }
+    }
+    validateRuntimeShape(descriptor);
+}
+function validateTuple(tuple) {
+    if (!carriers.includes(tuple.carrier) || !["dial", "listen"].includes(tuple.networkMode) ||
+        !["direct", "tunnel"].includes(tuple.path) || !["client", "server"].includes(tuple.sessionRole) ||
+        tuple.reliableStreams !== true || typeof tuple.datagrams !== "boolean" || typeof tuple.migration !== "boolean") {
+        throw new TypeError("invalid runtime capability tuple");
+    }
+    const deployment = tuple.path === "direct"
+        ? (tuple.networkMode === "dial" && tuple.sessionRole === "client") ||
+            (tuple.networkMode === "listen" && tuple.sessionRole === "server")
+        : tuple.networkMode === "dial";
+    if (!deployment)
+        throw new TypeError("invalid runtime capability deployment role");
+    if (tuple.carrier === "websocket" && (tuple.datagrams || tuple.migration)) {
+        throw new TypeError("WebSocket cannot advertise datagrams or migration");
+    }
+    const modes = tuple.securityModes;
+    if (!Array.isArray(modes) || (tuple.networkMode === "listen"
+        ? modes.length !== 0
+        : !(equalStrings(modes, ["ca"]) || equalStrings(modes, ["pin"]) || equalStrings(modes, ["ca", "pin"])))) {
+        throw new TypeError("invalid runtime capability security modes");
+    }
+}
+function validateRuntimeShape(descriptor) {
+    const id = `${descriptor.language}/${descriptor.runtime}`;
+    validateRegisteredTupleSets(descriptor, id);
+    if (id === "typescript/browser") {
+        validateReason(descriptor, "raw_quic", "browser_no_raw_udp");
+        for (const tuple of descriptor.tuples) {
+            if (tuple.carrier === "websocket" && !equalStrings(tuple.securityModes, ["ca"])) {
+                throw new TypeError("browser WebSocket is CA-only");
+            }
+            if (tuple.carrier === "webtransport" &&
+                !(equalStrings(tuple.securityModes, ["ca"]) || equalStrings(tuple.securityModes, ["ca", "pin"]))) {
+                throw new TypeError("invalid browser WebTransport security modes");
+            }
+            if (tuple.networkMode !== "dial" || tuple.migration ||
+                tuple.datagrams !== (tuple.carrier === "webtransport")) {
+                throw new TypeError("invalid browser tuple");
+            }
+        }
+    }
+    else if (id === "typescript/node") {
+        validateReason(descriptor, "webtransport", "node_webtransport_driver_unavailable");
+        for (const tuple of descriptor.tuples) {
+            if (!equalStrings(tuple.securityModes, tuple.networkMode === "listen" ? [] : ["ca", "pin"]) ||
+                tuple.migration || tuple.datagrams !== (tuple.carrier === "raw_quic")) {
+                throw new TypeError("invalid Node tuple");
+            }
+        }
+    }
+}
+function validateRegisteredTupleSets(descriptor, id) {
+    const expected = registeredTupleSets(id);
+    if (expected === undefined)
+        throw new TypeError("invalid runtime capability identity");
+    for (const carrier of carriers) {
+        const actual = descriptor.tuples.filter((tuple) => tuple.carrier === carrier);
+        const unsupported = descriptor.unsupported.find((entry) => entry.carrier === carrier);
+        const carrierExpected = expected[carrier];
+        if (unsupported !== undefined) {
+            if (actual.length !== 0 || carrierExpected.unsupportedReasons?.includes(unsupported.reason) !== true) {
+                throw new TypeError("runtime capability does not match its registered carrier set");
+            }
+            continue;
+        }
+        if (carrierExpected.tupleSets?.some((set) => equalTupleSets(actual, set)) !== true) {
+            throw new TypeError("runtime capability does not match its registered tuple set");
+        }
+    }
+}
+function registeredTupleSets(id) {
+    const ca = ["ca"];
+    const caPin = ["ca", "pin"];
+    const websocket = (modes) => registeredTuples("websocket", false, false, true, modes);
+    const websocket3 = (modes) => registeredTuples("websocket", false, false, false, modes);
+    const rawQuic4M = registeredTuples("raw_quic", true, true, true, caPin);
+    const rawQuic4N = registeredTuples("raw_quic", true, false, true, caPin);
+    const webTransport4 = registeredTuples("webtransport", true, false, true, caPin);
+    const webTransport3CA = registeredTuples("webtransport", true, false, false, ca);
+    const webTransport3Pin = registeredTuples("webtransport", true, false, false, caPin);
+    switch (id) {
+        case "go/native":
+            return {
+                raw_quic: { tupleSets: [rawQuic4M] },
+                websocket: { tupleSets: [websocket(caPin)] },
+                webtransport: { tupleSets: [webTransport4] },
+            };
+        case "typescript/browser":
+            return {
+                raw_quic: { unsupportedReasons: ["browser_no_raw_udp"] },
+                websocket: { tupleSets: [websocket3(ca)], unsupportedReasons: ["browser_websocket_api_unavailable"] },
+                webtransport: { tupleSets: [webTransport3CA, webTransport3Pin], unsupportedReasons: ["browser_webtransport_api_unavailable"] },
+            };
+        case "typescript/node":
+            return {
+                raw_quic: { tupleSets: [rawQuic4N], unsupportedReasons: ["node_native_transport_unavailable"] },
+                websocket: { tupleSets: [websocket(caPin)] },
+                webtransport: { unsupportedReasons: ["node_webtransport_driver_unavailable"] },
+            };
+        case "rust/native":
+            return {
+                raw_quic: { tupleSets: [rawQuic4M] },
+                websocket: { tupleSets: [websocket(caPin)] },
+                webtransport: { unsupportedReasons: ["driver_unavailable"] },
+            };
+        case "swift/ios":
+        case "swift/macos":
+            return {
+                raw_quic: { unsupportedReasons: ["swift_apple_client_profile_excludes_raw_quic"] },
+                websocket: { tupleSets: [websocket3(caPin)] },
+                webtransport: { unsupportedReasons: ["swift_apple_client_profile_excludes_webtransport"] },
+            };
+        case "swift/linux":
+            return {
+                raw_quic: { unsupportedReasons: ["swift_apple_client_profile_excludes_raw_quic"] },
+                websocket: { unsupportedReasons: ["websocket_adapter_not_supported_on_linux"] },
+                webtransport: { unsupportedReasons: ["swift_apple_client_profile_excludes_webtransport"] },
+            };
+        default:
+            return undefined;
+    }
+}
+function registeredTuples(carrier, datagrams, migration, includeListener, securityModes) {
+    const tuples = [
+        { carrier, datagrams, migration, networkMode: "dial", path: "direct", reliableStreams: true, securityModes, sessionRole: "client" },
+        { carrier, datagrams, migration, networkMode: "dial", path: "tunnel", reliableStreams: true, securityModes, sessionRole: "client" },
+        { carrier, datagrams, migration, networkMode: "dial", path: "tunnel", reliableStreams: true, securityModes, sessionRole: "server" },
+    ];
+    if (includeListener) {
+        tuples.push({ carrier, datagrams, migration: false, networkMode: "listen", path: "direct", reliableStreams: true, securityModes: [], sessionRole: "server" });
+    }
+    return tuples;
+}
+function equalTupleSets(actual, expected) {
+    return actual.length === expected.length && actual.every((tuple, index) => tupleKey(tuple) === tupleKey(expected[index]));
+}
+function tupleKey(tuple) {
+    return JSON.stringify([
+        tuple.carrier, tuple.networkMode, tuple.sessionRole, tuple.path,
+        tuple.reliableStreams, tuple.datagrams, tuple.migration, [...tuple.securityModes],
+    ]);
+}
+function validateReason(descriptor, carrier, expected) {
+    const item = descriptor.unsupported.find((entry) => entry.carrier === carrier);
+    if (item !== undefined && item.reason !== expected && !(carrier === "raw_quic" && descriptor.runtime === "browser" && item.reason === "browser_no_raw_udp"))
+        throw new TypeError("invalid unsupported reason for runtime");
+}
+function decodeDescriptor(input) {
+    const object = exactObject(input, ["language", "runtime", "schemaVersion", "tuples", "unsupported"]);
+    if (typeof object.language !== "string" || typeof object.runtime !== "string" || object.schemaVersion !== 3 ||
+        !Array.isArray(object.tuples) || !Array.isArray(object.unsupported)) {
+        throw new TypeError("invalid runtime capability descriptor");
+    }
+    const tuples = object.tuples.map((input) => {
+        const value = exactObject(input, [
+            "carrier", "datagrams", "migration", "networkMode", "path", "reliableStreams", "securityModes", "sessionRole",
+        ]);
+        if (typeof value.carrier !== "string" || typeof value.networkMode !== "string" ||
+            typeof value.path !== "string" || typeof value.sessionRole !== "string" ||
+            typeof value.datagrams !== "boolean" || typeof value.migration !== "boolean" ||
+            value.reliableStreams !== true || !Array.isArray(value.securityModes) ||
+            value.securityModes.some((mode) => mode !== "ca" && mode !== "pin")) {
+            throw new TypeError("invalid runtime capability tuple");
+        }
+        return {
+            carrier: value.carrier,
+            datagrams: value.datagrams,
+            migration: value.migration,
+            networkMode: value.networkMode,
+            path: value.path,
+            reliableStreams: true,
+            securityModes: value.securityModes,
+            sessionRole: value.sessionRole,
+        };
+    });
+    const unsupported = object.unsupported.map((input) => {
+        const value = exactObject(input, ["carrier", "reason"]);
+        if (typeof value.carrier !== "string" || typeof value.reason !== "string") {
+            throw new TypeError("invalid unsupported runtime carrier");
+        }
+        return { carrier: value.carrier, reason: value.reason };
+    });
+    const descriptor = freezeDescriptor({
+        language: object.language,
+        runtime: object.runtime,
+        schemaVersion: 3,
+        tuples,
+        unsupported,
+    });
+    validateRuntimeCapabilityDescriptorV3(descriptor);
+    return descriptor;
+}
+function freezeDescriptor(descriptor) {
+    return Object.freeze({
+        ...descriptor,
+        tuples: Object.freeze(descriptor.tuples.map((tuple) => Object.freeze({
+            ...tuple,
+            securityModes: Object.freeze([...tuple.securityModes]),
+        }))),
+        unsupported: Object.freeze(descriptor.unsupported.map((entry) => Object.freeze({ ...entry }))),
+    });
+}
+function exactObject(input, keys) {
+    if (typeof input !== "object" || input === null || Array.isArray(input))
+        throw new TypeError("expected object");
+    const object = input;
+    const actual = Object.keys(object).sort(compareASCII);
+    const expected = [...keys].sort(compareASCII);
+    if (!equalStrings(actual, expected))
+        throw new TypeError("object has unknown or missing fields");
+    return object;
+}
+function compareTuple(left, right) {
+    return compareLists([left.carrier, left.networkMode, left.sessionRole, left.path], [right.carrier, right.networkMode, right.sessionRole, right.path]);
+}
+function compareLists(left, right) {
+    for (let index = 0; index < left.length; index += 1) {
+        const order = compareASCII(left[index], right[index]);
+        if (order !== 0)
+            return order;
+    }
+    return 0;
+}
+function compareASCII(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function equalStrings(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}

package/dist/v3/carrier.d.ts

@@ -0,0 +1,84 @@
+import type { CarrierKind, OperationOptionsV3, PathKind } from "./contract.js";
+export type CarrierErrorCode = "aborted" | "closed" | "reset" | "stop_sending" | "stop_sending_unavailable" | "write_closed" | "datagram_unavailable";
+export declare class CarrierError extends Error {
+    readonly code: CarrierErrorCode;
+    readonly cause?: unknown | undefined;
+    constructor(code: CarrierErrorCode, message: string, cause?: unknown | undefined);
+}
+export interface CarrierStreamV3 {
+    read(options?: OperationOptionsV3): Promise<Uint8Array | null>;
+    write(data: Uint8Array, options?: OperationOptionsV3): Promise<number>;
+    closeWrite(): Promise<void>;
+    stopSending(): Promise<void>;
+    reset(): Promise<void>;
+    /**
+     * Synchronously initiates idempotent forced teardown. Pending and future
+     * stream primitives must settle, but this call does not await cleanup.
+     */
+    abort(error?: Error): void;
+}
+export interface CarrierUnreliableDatagramsV3 {
+    readonly maxDatagramSize: number;
+    send(data: Uint8Array, options?: Readonly<{
+        signal?: AbortSignal;
+        expiresAt?: number;
+    }>): Promise<"accepted" | "dropped_budget" | "dropped_expired" | "dropped_carrier">;
+    receive(options?: OperationOptionsV3): Promise<Uint8Array>;
+}
+export interface CarrierSessionV3 {
+    readonly kind: CarrierKind;
+    readonly path: PathKind;
+    readonly inboundBidirectionalStreamCapacity: number;
+    readonly unreliableDatagrams?: CarrierUnreliableDatagramsV3 | undefined;
+    openStream(options?: OperationOptionsV3): Promise<CarrierStreamV3>;
+    acceptStream(options?: OperationOptionsV3): Promise<CarrierStreamV3>;
+    waitTermination(): Promise<void>;
+    close(error?: Readonly<{
+        code: number;
+        reason: string;
+    }>): Promise<void>;
+    /**
+     * Synchronously initiates idempotent forced teardown. Pending and future
+     * session and stream primitives must settle, but this call does not await cleanup.
+     */
+    abort(error?: Readonly<{
+        code: number;
+        reason: string;
+    }>): void;
+}
+export type NativeCarrierStreamV3 = Readonly<{
+    read(): Promise<Uint8Array | null>;
+    write(data: Uint8Array): Promise<number>;
+    closeWrite(): Promise<void>;
+    stopSending(): Promise<void>;
+    reset(): Promise<void>;
+    /** Cancels pending local primitives without initiating peer-visible teardown. */
+    cancelPending?(): void;
+    /** See {@link CarrierStreamV3.abort}. */
+    abort(error?: Error): void;
+}>;
+export type NativeCarrierSessionV3 = Readonly<{
+    kind: "webtransport" | "raw_quic";
+    path: PathKind;
+    inboundBidirectionalStreamCapacity: number;
+    unreliableDatagrams?: CarrierUnreliableDatagramsV3 | undefined;
+    openStream(options?: OperationOptionsV3): Promise<NativeCarrierStreamV3>;
+    acceptStream(options?: OperationOptionsV3): Promise<NativeCarrierStreamV3>;
+    waitTermination(): Promise<void>;
+    close(error?: Readonly<{
+        code: number;
+        reason: string;
+    }>): Promise<void>;
+    /** See {@link CarrierSessionV3.abort}. */
+    abort(error?: Readonly<{
+        code: number;
+        reason: string;
+    }>): void;
+}>;
+export declare function adaptNativeCarrierSessionV3(native: NativeCarrierSessionV3): CarrierSessionV3;
+export declare function createMemoryCarrierPairV3(options: Readonly<{
+    kind: CarrierKind;
+    path: PathKind;
+    inboundBidirectionalStreamCapacity: number;
+    maxPendingStreams?: number;
+}>): readonly [CarrierSessionV3, CarrierSessionV3];