@floegence/flowersec-core 2.5.4 → 3.0.0

package/dist/v3/artifactLease.d.ts

@@ -0,0 +1,17 @@
+import type { ArtifactV3 } from "./artifact.js";
+export declare class ArtifactLeaseV3Error extends Error {
+    readonly code = "already_consumed";
+    constructor();
+}
+export declare class ArtifactLeaseV3 {
+    private readonly leaseBrand;
+    private constructor();
+}
+export declare class ClaimedArtifactLeaseV3 {
+    private readonly claimBrand;
+    private constructor();
+}
+export declare function claimArtifactLeaseV3(lease: ArtifactLeaseV3): ClaimedArtifactLeaseV3;
+export declare function claimedArtifactV3(claim: ClaimedArtifactLeaseV3): ArtifactV3;
+export declare function commitArtifactLeaseSpendV3(claim: ClaimedArtifactLeaseV3, signal?: AbortSignal): Promise<void>;
+export declare function retireArtifactLeaseV3(claim: ClaimedArtifactLeaseV3): Promise<void>;

package/dist/v3/artifactLease.js

@@ -0,0 +1,109 @@
+export class ArtifactLeaseV3Error extends Error {
+    code = "already_consumed";
+    constructor() {
+        super("Flowersec artifact lease is no longer available");
+        this.name = "ArtifactLeaseError";
+    }
+}
+const leaseStates = new WeakMap();
+const claimStates = new WeakMap();
+export class ArtifactLeaseV3 {
+    constructor() { }
+}
+export class ClaimedArtifactLeaseV3 {
+    constructor() { }
+}
+/** @internal Artifact sources construct idle one-shot leases through this boundary. */
+export function createArtifactLeaseV3Internal(artifact, commitSpend, retireCleanup) {
+    if (typeof commitSpend !== "function" || (retireCleanup !== undefined && typeof retireCleanup !== "function")) {
+        throw new TypeError("invalid Flowersec v3 artifact lease callbacks");
+    }
+    const lease = new ArtifactLeaseV3();
+    leaseStates.set(lease, {
+        artifact,
+        status: "idle",
+        commit: commitSpend,
+        cleanup: retireCleanup,
+        cleanupStarted: false,
+    });
+    return Object.freeze(lease);
+}
+/** @internal Creates another handle over the same atomic state for race tests and wrappers. */
+export function duplicateArtifactLeaseHandleV3(lease) {
+    const state = leaseStates.get(lease);
+    if (state === undefined)
+        throw new ArtifactLeaseV3Error();
+    const copy = new ArtifactLeaseV3();
+    leaseStates.set(copy, state);
+    return Object.freeze(copy);
+}
+export function claimArtifactLeaseV3(lease) {
+    const state = leaseStates.get(lease);
+    if (state === undefined || state.status !== "idle")
+        throw new ArtifactLeaseV3Error();
+    state.status = "claimed";
+    const claim = new ClaimedArtifactLeaseV3();
+    claimStates.set(claim, state);
+    return Object.freeze(claim);
+}
+export function claimedArtifactV3(claim) {
+    const state = claimStates.get(claim);
+    if (state === undefined || (state.status !== "claimed" && state.status !== "spending")) {
+        throw new ArtifactLeaseV3Error();
+    }
+    return state.artifact;
+}
+export async function commitArtifactLeaseSpendV3(claim, signal) {
+    const state = claimStates.get(claim);
+    if (state === undefined || state.status !== "claimed")
+        throw new ArtifactLeaseV3Error();
+    state.status = "spending";
+    const callback = Promise.resolve().then(() => state.commit(signal));
+    let abort;
+    try {
+        if (signal === undefined) {
+            await callback;
+        }
+        else {
+            const canceled = new Promise((_, reject) => {
+                abort = () => reject(signal.reason ?? new Error("artifact spend canceled"));
+                if (signal.aborted)
+                    abort();
+                else
+                    signal.addEventListener("abort", abort, { once: true });
+            });
+            await Promise.race([callback, canceled]);
+        }
+    }
+    finally {
+        if (signal !== undefined && abort !== undefined)
+            signal.removeEventListener("abort", abort);
+        state.status = "consumed";
+        // A cancellation result is authoritative for the lease even when an
+        // application callback ignores the signal and settles later.
+        void callback.catch(() => undefined);
+    }
+}
+export async function retireArtifactLeaseV3(claim) {
+    const state = claimStates.get(claim);
+    if (state === undefined || state.status !== "claimed")
+        throw new ArtifactLeaseV3Error();
+    state.status = "retired";
+    if (state.cleanup === undefined || state.cleanupStarted)
+        return;
+    state.cleanupStarted = true;
+    try {
+        await state.cleanup();
+    }
+    catch {
+        // Retirement is final. Cleanup failures are deliberately not allowed to
+        // restore or leak ownership of a one-shot credential.
+    }
+}
+/** @internal */
+export function artifactLeaseStateV3(lease) {
+    const state = lease instanceof ArtifactLeaseV3 ? leaseStates.get(lease) : claimStates.get(lease);
+    if (state === undefined)
+        throw new ArtifactLeaseV3Error();
+    return state.status;
+}

package/dist/v3/browserRuntime.d.ts

@@ -0,0 +1,37 @@
+import { type RuntimeCapabilityDescriptorV3 } from "./capability.js";
+import type { CanonicalArtifactCandidateV3 } from "./artifact.js";
+import type { NativeCarrierSessionV3 } from "./carrier.js";
+type BrowserFeaturesV3 = Readonly<{
+    WebSocket?: unknown;
+    WebTransport?: unknown;
+    navigator?: Readonly<{
+        userAgentData?: Readonly<{
+            getHighEntropyValues(hints: readonly string[]): Promise<unknown>;
+        }>;
+    }>;
+}>;
+type WebTransportLikeV3 = Readonly<{
+    ready: Promise<void>;
+    close(options?: Readonly<{
+        closeCode?: number;
+        reason?: string;
+    }>): void;
+}>;
+type WebTransportConstructorV3 = new (url: string, options?: Readonly<{
+    serverCertificateHashes: readonly Readonly<{
+        algorithm: "sha-256";
+        value: ArrayBuffer;
+    }>[];
+}>) => WebTransportLikeV3;
+export declare class BrowserRuntimeCapabilityRegistryV3 {
+    #private;
+    private constructor();
+    static create(features?: BrowserFeaturesV3): Promise<BrowserRuntimeCapabilityRegistryV3>;
+    snapshot(): RuntimeCapabilityDescriptorV3;
+    pinEnabled(): boolean;
+    invalidatePinSupport(): boolean;
+    webTransportConstructor(): WebTransportConstructorV3 | undefined;
+}
+export declare function createBrowserWebTransportV3(candidate: CanonicalArtifactCandidateV3, attemptNowUnixSeconds: number, capabilitySnapshot: RuntimeCapabilityDescriptorV3, registry: BrowserRuntimeCapabilityRegistryV3, signal?: AbortSignal): Promise<WebTransportLikeV3>;
+export declare function createBrowserWebTransportCarrierV3(candidate: CanonicalArtifactCandidateV3, attemptNowUnixSeconds: number, capabilitySnapshot: RuntimeCapabilityDescriptorV3, registry: BrowserRuntimeCapabilityRegistryV3, inboundBidirectionalStreamCapacity: number, signal?: AbortSignal): Promise<NativeCarrierSessionV3>;
+export {};

package/dist/v3/browserRuntime.js

@@ -0,0 +1,197 @@
+import { defineRuntimeCapabilityDescriptorV3 } from "./capability.js";
+import { snapshotTransportSecurityPolicyV3, TransportFailureV3 } from "./security.js";
+import { adaptWebTransportCarrierSessionV3, hasWebTransportConstructorSurfaceV3, } from "./webTransportCarrier.js";
+import { FLOWERSEC_V3_PATHS, FLOWERSEC_V3_WIRE_PROFILES } from "./transportConstants.js";
+const PIN_BROWSER_VERSION = "151.0.7922.34";
+const webSocketTuples = tuplesFor("websocket", false, ["ca"]);
+const webTransportCATuples = tuplesFor("webtransport", true, ["ca"]);
+const webTransportPinTuples = tuplesFor("webtransport", true, ["ca", "pin"]);
+export class BrowserRuntimeCapabilityRegistryV3 {
+    #features;
+    #hasWebSocket;
+    #hasWebTransport;
+    #pinState;
+    constructor(features, pinEnabled) {
+        this.#features = features;
+        this.#hasWebSocket = typeof features.WebSocket === "function";
+        this.#hasWebTransport = hasWebTransportConstructorSurfaceV3(features.WebTransport);
+        this.#pinState = pinEnabled ? "enabled" : "ca_only";
+    }
+    static async create(features = globalThis) {
+        return new BrowserRuntimeCapabilityRegistryV3(features, await exactChromiumPinProvider(features));
+    }
+    snapshot() {
+        const tuples = [];
+        const unsupported = [
+            { carrier: "raw_quic", reason: "browser_no_raw_udp" },
+        ];
+        if (this.#hasWebSocket)
+            tuples.push(...webSocketTuples);
+        else
+            unsupported.push({ carrier: "websocket", reason: "browser_websocket_api_unavailable" });
+        if (this.#hasWebTransport) {
+            tuples.push(...(this.#pinState === "enabled" ? webTransportPinTuples : webTransportCATuples));
+        }
+        else {
+            unsupported.push({ carrier: "webtransport", reason: "browser_webtransport_api_unavailable" });
+        }
+        unsupported.sort((left, right) => left.carrier < right.carrier ? -1 : left.carrier > right.carrier ? 1 : 0);
+        return defineRuntimeCapabilityDescriptorV3("browser", tuples, unsupported);
+    }
+    pinEnabled() {
+        return this.#pinState === "enabled";
+    }
+    invalidatePinSupport() {
+        if (this.#pinState === "ca_only")
+            return false;
+        this.#pinState = "ca_only";
+        return true;
+    }
+    webTransportConstructor() {
+        return hasWebTransportConstructorSurfaceV3(this.#features.WebTransport)
+            ? this.#features.WebTransport
+            : undefined;
+    }
+}
+export async function createBrowserWebTransportV3(candidate, attemptNowUnixSeconds, capabilitySnapshot, registry, signal) {
+    if (candidate.carrier !== "webtransport")
+        throw new TransportFailureV3("invalid_artifact");
+    const path = pathFromProfile(candidate.wire_profile);
+    validateNormalizedBrowserURL(candidate.normalized_url, path);
+    const tuple = capabilitySnapshot.tuples.find((entry) => entry.carrier === "webtransport" && entry.networkMode === "dial" && entry.path === path);
+    const modes = tuple?.securityModes ?? [];
+    const policy = snapshotTransportSecurityPolicyV3(candidate.tls, attemptNowUnixSeconds, modes);
+    if (policy.mode === "pin" && !registry.pinEnabled())
+        throw new TransportFailureV3("tls_unsupported");
+    const Constructor = registry.webTransportConstructor();
+    if (Constructor === undefined)
+        throw new TransportFailureV3("tls_unsupported");
+    if (signal?.aborted === true)
+        throw signal.reason;
+    let transport;
+    try {
+        transport = policy.mode === "ca"
+            ? new Constructor(candidate.normalized_url)
+            : new Constructor(candidate.normalized_url, {
+                serverCertificateHashes: policy.activeLeafDerSHA256.map((value) => ({
+                    algorithm: "sha-256",
+                    value: exactArrayBuffer(value),
+                })),
+            });
+    }
+    catch (error) {
+        if (policy.mode === "pin" && isNotSupportedError(error)) {
+            registry.invalidatePinSupport();
+            throw new TransportFailureV3("tls_unsupported", undefined, error);
+        }
+        throw new TransportFailureV3("connection_failed", undefined, error);
+    }
+    try {
+        await raceAbort(transport.ready, signal);
+        return transport;
+    }
+    catch (error) {
+        try {
+            transport.close({ closeCode: 6, reason: "WebTransport start failed" });
+        }
+        catch { /* best effort */ }
+        if (error instanceof BrowserRuntimeAbortV3)
+            throw error.reason;
+        throw new TransportFailureV3("connection_failed", policy.mode === "pin" ? "browser_pin_opaque" : undefined, error);
+    }
+}
+export async function createBrowserWebTransportCarrierV3(candidate, attemptNowUnixSeconds, capabilitySnapshot, registry, inboundBidirectionalStreamCapacity, signal) {
+    const path = pathFromProfile(candidate.wire_profile);
+    const transport = await createBrowserWebTransportV3(candidate, attemptNowUnixSeconds, capabilitySnapshot, registry, signal);
+    try {
+        return adaptWebTransportCarrierSessionV3(transport, { path, inboundBidirectionalStreamCapacity });
+    }
+    catch (error) {
+        try {
+            transport.close({ closeCode: 6, reason: "WebTransport adapter failed" });
+        }
+        catch { /* best effort */ }
+        throw error;
+    }
+}
+async function exactChromiumPinProvider(features) {
+    if (!hasWebTransportConstructorSurfaceV3(features.WebTransport))
+        return false;
+    const provider = features.navigator?.userAgentData;
+    if (provider === undefined || typeof provider.getHighEntropyValues !== "function")
+        return false;
+    let value;
+    try {
+        value = await provider.getHighEntropyValues(["fullVersionList"]);
+    }
+    catch {
+        return false;
+    }
+    if (typeof value !== "object" || value === null)
+        return false;
+    const list = value.fullVersionList;
+    if (!Array.isArray(list))
+        return false;
+    const chromium = list.filter((entry) => typeof entry === "object" && entry !== null &&
+        entry.brand === "Chromium");
+    if (chromium.length !== 1)
+        return false;
+    const version = chromium[0].version;
+    return typeof version === "string" && /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/.test(version) &&
+        version === PIN_BROWSER_VERSION;
+}
+function tuplesFor(carrier, datagrams, securityModes) {
+    return Object.freeze([
+        { carrier, datagrams, migration: false, networkMode: "dial", path: "direct", reliableStreams: true, securityModes, sessionRole: "client" },
+        { carrier, datagrams, migration: false, networkMode: "dial", path: "tunnel", reliableStreams: true, securityModes, sessionRole: "client" },
+        { carrier, datagrams, migration: false, networkMode: "dial", path: "tunnel", reliableStreams: true, securityModes, sessionRole: "server" },
+    ]);
+}
+function validateNormalizedBrowserURL(raw, path) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new TransportFailureV3("invalid_artifact");
+    }
+    const expectedPath = FLOWERSEC_V3_PATHS.webtransport[path];
+    if (parsed.href !== raw || parsed.protocol !== "https:" || parsed.username !== "" || parsed.password !== "" ||
+        parsed.pathname !== expectedPath || parsed.search !== "" || parsed.hash !== "") {
+        throw new TransportFailureV3("invalid_artifact");
+    }
+}
+function pathFromProfile(profile) {
+    if (profile === FLOWERSEC_V3_WIRE_PROFILES.direct)
+        return "direct";
+    if (profile === FLOWERSEC_V3_WIRE_PROFILES.tunnel)
+        return "tunnel";
+    throw new TransportFailureV3("invalid_artifact");
+}
+function exactArrayBuffer(value) {
+    return value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength);
+}
+function isNotSupportedError(error) {
+    return error instanceof DOMException ? error.name === "NotSupportedError" :
+        typeof error === "object" && error !== null && error.name === "NotSupportedError";
+}
+class BrowserRuntimeAbortV3 {
+    reason;
+    constructor(reason) {
+        this.reason = reason;
+    }
+}
+async function raceAbort(promise, signal) {
+    if (signal === undefined)
+        return await promise;
+    if (signal.aborted)
+        throw new BrowserRuntimeAbortV3(signal.reason);
+    return await new Promise((resolve, reject) => {
+        const abort = () => {
+            signal.removeEventListener("abort", abort);
+            reject(new BrowserRuntimeAbortV3(signal.reason));
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        void promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    });
+}

package/dist/v3/browserSessionRuntime.d.ts

@@ -0,0 +1,2 @@
+import type { SessionProtocolRuntimeV3 } from "./session.js";
+export declare const browserSessionRuntimeV3: SessionProtocolRuntimeV3;

package/dist/v3/browserSessionRuntime.js

@@ -0,0 +1,21 @@
+import { RuntimeError } from "../runtime/errors.js";
+export const browserSessionRuntimeV3 = Object.freeze({
+    entropy(length) {
+        requireLength(length);
+        const runtime = globalThis.crypto;
+        if (runtime === undefined || typeof runtime.getRandomValues !== "function") {
+            throw new RuntimeError("runtime_unsupported", "browser cryptographic entropy is unavailable");
+        }
+        const output = new Uint8Array(length);
+        runtime.getRandomValues(output);
+        return output;
+    },
+    monotonicMilliseconds() {
+        return performance.now();
+    },
+});
+function requireLength(length) {
+    if (!Number.isSafeInteger(length) || length < 1 || length > 65_536) {
+        throw new RangeError("entropy length must be an integer from 1 to 65536");
+    }
+}

package/dist/v3/capability.d.ts

@@ -0,0 +1,32 @@
+import type { CarrierKind, PathKind } from "../public/contract.js";
+export type TransportSecurityModeV3 = "ca" | "pin";
+export type NetworkModeV3 = "dial" | "listen";
+export type SessionRoleV3 = "client" | "server";
+export type RuntimeCapabilityTupleV3 = Readonly<{
+    carrier: CarrierKind;
+    datagrams: boolean;
+    migration: boolean;
+    networkMode: NetworkModeV3;
+    path: PathKind;
+    reliableStreams: true;
+    securityModes: readonly TransportSecurityModeV3[];
+    sessionRole: SessionRoleV3;
+}>;
+export type UnsupportedRuntimeCarrierV3 = Readonly<{
+    carrier: CarrierKind;
+    reason: string;
+}>;
+export type RuntimeCapabilityDescriptorV3 = Readonly<{
+    language: string;
+    runtime: string;
+    schemaVersion: 3;
+    tuples: readonly RuntimeCapabilityTupleV3[];
+    unsupported: readonly UnsupportedRuntimeCarrierV3[];
+}>;
+export declare function defineRuntimeCapabilityDescriptorV3(runtime: "browser" | "node", tuples: readonly RuntimeCapabilityTupleV3[], unsupported: readonly UnsupportedRuntimeCarrierV3[]): RuntimeCapabilityDescriptorV3;
+export declare function encodeRuntimeCapabilityDescriptorV3(descriptor: RuntimeCapabilityDescriptorV3): string;
+export declare function decodeRuntimeCapabilityDescriptorV3(raw: string | Uint8Array): RuntimeCapabilityDescriptorV3;
+export declare function runtimeCapabilityDigestV3(descriptor: RuntimeCapabilityDescriptorV3): Uint8Array;
+export declare function runtimeCapabilityDigestHexV3(descriptor: RuntimeCapabilityDescriptorV3): string;
+export declare function supportsCandidateSecurityV3(descriptor: RuntimeCapabilityDescriptorV3, carrier: CarrierKind, path: PathKind, sessionRole: SessionRoleV3, mode: TransportSecurityModeV3): boolean;
+export declare function validateRuntimeCapabilityDescriptorV3(descriptor: RuntimeCapabilityDescriptorV3): void;