@floegence/flowersec-core 2.5.3 → 3.0.0

package/dist/v2/protocol.js

@@ -616,68 +616,59 @@ export function canonicalStreamMetadataJSONV2Internal(value) {
     if (!isJSONObject(value))
         throw new ProtocolV2Error("OPEN metadata root must be an object");
     const state = { nodes: -1 };
-    validateMetadataValue(value, 1, state);
-    const canonical = canonicalJSONString(value);
+    const canonical = canonicalValidatedMetadataJSONString(value, 1, state);
     if (encoder.encode(canonical).length > MAX_OPEN_METADATA_BYTES) {
         throw new ProtocolV2Error("OPEN metadata is too large");
     }
     return canonical;
 }
-function validateMetadataValue(value, depth, state) {
+function canonicalValidatedMetadataJSONString(value, depth, state) {
     if (depth > MAX_OPEN_METADATA_DEPTH)
         throw new ProtocolV2Error("OPEN metadata exceeds depth limit");
     state.nodes += 1;
     if (state.nodes > MAX_OPEN_METADATA_NODES)
         throw new ProtocolV2Error("OPEN metadata exceeds node limit");
-    if (value === null || typeof value === "boolean")
-        return;
+    if (value === null)
+        return "null";
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
     if (typeof value === "number") {
-        if (!Number.isSafeInteger(value))
+        if (!Number.isSafeInteger(value) || Object.is(value, -0))
             throw new ProtocolV2Error("OPEN metadata number is not an I-JSON safe integer");
-        return;
+        return value.toString(10);
     }
     if (typeof value === "string") {
         if (!validOpenUnicodeString(value, MAX_OPEN_METADATA_STRING_BYTES, true)) {
             throw new ProtocolV2Error("invalid OPEN metadata string");
         }
-        return;
+        return quoteCanonicalJSONString(value);
     }
     if (Array.isArray(value)) {
-        if (value.length > MAX_OPEN_METADATA_ARRAY)
+        const length = value.length;
+        if (length > MAX_OPEN_METADATA_ARRAY)
             throw new ProtocolV2Error("OPEN metadata array is too large");
-        for (const item of value)
-            validateMetadataValue(item, depth + 1, state);
-        return;
+        const items = new Array(length);
+        for (let index = 0; index < length; index++) {
+            const item = value[index];
+            items[index] = canonicalValidatedMetadataJSONString(item, depth + 1, state);
+        }
+        return `[${items.join(",")}]`;
     }
     if (!isJSONObject(value))
         throw new ProtocolV2Error("unsupported OPEN metadata value");
-    const keys = Object.keys(value);
+    const keys = Object.keys(value).sort();
     if (keys.length > MAX_OPEN_METADATA_KEYS)
         throw new ProtocolV2Error("OPEN metadata object is too large");
+    const members = new Array(keys.length);
+    let index = 0;
     for (const key of keys) {
         if (!validOpenUnicodeString(key, MAX_OPEN_METADATA_KEY_BYTES, false)) {
             throw new ProtocolV2Error("invalid OPEN metadata key");
         }
-        validateMetadataValue(value[key], depth + 1, state);
+        const item = value[key];
+        members[index++] = `${quoteCanonicalJSONString(key)}:${canonicalValidatedMetadataJSONString(item, depth + 1, state)}`;
     }
-}
-function canonicalJSONString(value) {
-    if (value === null)
-        return "null";
-    if (typeof value === "boolean")
-        return value ? "true" : "false";
-    if (typeof value === "number")
-        return value.toString(10);
-    if (typeof value === "string")
-        return quoteCanonicalJSONString(value);
-    if (Array.isArray(value))
-        return `[${value.map(canonicalJSONString).join(",")}]`;
-    if (!isJSONObject(value))
-        throw new ProtocolV2Error("unsupported OPEN metadata value");
-    return `{${Object.keys(value)
-        .sort()
-        .map((key) => `${quoteCanonicalJSONString(key)}:${canonicalJSONString(value[key])}`)
-        .join(",")}}`;
+    return `{${members.join(",")}}`;
 }
 function quoteCanonicalJSONString(value) {
     return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;

package/dist/v2/publicSession.js

@@ -1,5 +1,6 @@
 import { SessionError } from "./contract.js";
 import { createStreamMetadataV2, streamMetadataValuesV2 } from "./streamMetadata.js";
+import { assertRpcTypeId } from "../rpc/validate.js";
 /** @internal */
 export function projectSessionV2(session) {
     const notificationOwner = {
@@ -132,6 +133,7 @@ function projectRpcPeerV2(peer, notificationOwner) {
     return Object.freeze({
         async call(typeId, payload, decodeResponse, options) {
             try {
+                assertRpcTypeId(typeId);
                 assertJsonValue(payload);
                 const result = await peer.call(typeId, payload, options?.signal);
                 if (result.error !== undefined) {
@@ -146,6 +148,7 @@ function projectRpcPeerV2(peer, notificationOwner) {
         },
         async notify(typeId, payload, options) {
             try {
+                assertRpcTypeId(typeId);
                 assertJsonValue(payload);
                 if (options?.signal?.aborted)
                     throw options.signal.reason ?? new DOMException("The operation was aborted", "AbortError");
@@ -156,6 +159,7 @@ function projectRpcPeerV2(peer, notificationOwner) {
             }
         },
         onNotify(typeId, decodePayload, handler) {
+            assertRpcTypeId(typeId);
             if (notificationOwner.closed)
                 return () => undefined;
             const unsubscribe = peer.onNotify(typeId, (payload) => {

package/dist/v2/session.d.ts

@@ -91,6 +91,7 @@ export declare class SessionV2 implements SessionV2Contract {
     private controlReceiveEpoch;
     private controlReceiveSequence;
     private controlWriteTail;
+    private controlTerminalSealed;
     private nextLogicalID;
     private receivedGoAway;
     private receivedGoAwayLastAccepted;
@@ -164,6 +165,10 @@ export declare class SessionV2 implements SessionV2Contract {
     private acceptCarrierStreamAfterFSS2;
     private resetInboundBeforeDelivery;
     private sendControl;
+    private sendControlResponse;
+    private sendControlCleanup;
+    private sendTerminalControl;
+    private writeControl;
     private readControl;
     private controlLoop;
     private closeOnce;

package/dist/v2/session.js

@@ -96,6 +96,7 @@ export class SessionV2 {
     controlReceiveEpoch = 0;
     controlReceiveSequence = 0n;
     controlWriteTail = Promise.resolve();
+    controlTerminalSealed = false;
     nextLogicalID;
     receivedGoAway = false;
     receivedGoAwayLastAccepted = 0n;
@@ -312,10 +313,11 @@ export class SessionV2 {
         this.releaseStream(stream);
         let controlConfirmed = false;
         try {
-            await this.sendControl(InnerTypeV2.StreamReset, idReason(stream.id, 6));
-            this.commitLocalReset(stream.id);
-            if (stream.hasRemoteFIN())
-                controlConfirmed = await this.confirmControlDelivery();
+            if (await this.sendControlCleanup(InnerTypeV2.StreamReset, idReason(stream.id, 6))) {
+                this.commitLocalReset(stream.id);
+                if (stream.hasRemoteFIN())
+                    controlConfirmed = await this.confirmControlDelivery();
+            }
         }
         catch (cause) {
             this.fail(asError(cause));
@@ -343,6 +345,8 @@ export class SessionV2 {
         this.cleanupEpochRoots();
     }
     async confirmControlDelivery() {
+        if (this.lifecycle !== "open" || this.controlTerminalSealed)
+            return false;
         const nonce = this.nextPing++;
         const pending = deferred();
         this.pings.set(nonce, pending);
@@ -567,33 +571,87 @@ export class SessionV2 {
     async resetInboundBeforeDelivery(id, carrierStream) {
         await carrierStream.reset().catch(() => undefined);
         try {
-            await this.sendControl(InnerTypeV2.StreamReset, idReason(id, 3));
-            this.peerLedger.localResetCommitted(id);
+            if (await this.sendControlCleanup(InnerTypeV2.StreamReset, idReason(id, 3))) {
+                this.peerLedger.localResetCommitted(id);
+            }
         }
         catch (error) {
             this.fail(asError(error));
         }
     }
     async sendControl(type, payload, signal) {
+        if (this.controlTerminalSealed) {
+            throw this.terminalError ?? new SessionV2Error("closed", "Flowersec v2 control stream is sealed");
+        }
         const task = this.controlWriteTail.then(async () => {
             if (this.lifecycle === "closed")
                 throw this.terminalError ?? new SessionV2Error("closed", "Flowersec v2 session closed");
-            const inner = encodeInnerRecordV2(type, payload);
-            const roots = this.rootForSend(this.controlSendEpoch);
-            const material = deriveControlMaterial(roots.controlRoot, this.h3, this.sendDirection, this.controlSendEpoch);
-            const header = {
-                epoch: this.controlSendEpoch,
-                sequence: this.controlSendSequence,
-                ciphertextLength: inner.length + 16,
-            };
-            const ciphertext = sealRecord(this.config.suite, material, this.h3, 0n, this.sendDirection, header, inner);
-            this.controlSendSequence += 1n;
-            await writeAll(this.control, concat(encodeRecordHeader(header), ciphertext), signal);
-            this.markAuthenticatedActivity();
+            await this.writeControl(type, payload, signal);
         });
         this.controlWriteTail = task.catch(() => undefined);
         await task;
     }
+    async sendControlResponse(type, payload) {
+        if (this.lifecycle !== "open" || this.controlTerminalSealed)
+            return false;
+        const task = this.controlWriteTail.then(async () => {
+            if (this.lifecycle !== "open" || this.controlTerminalSealed)
+                return false;
+            await this.writeControl(type, payload);
+            return true;
+        });
+        this.controlWriteTail = task.then(() => undefined, () => undefined);
+        return await task;
+    }
+    async sendControlCleanup(type, payload) {
+        if (this.controlTerminalSealed || this.lifecycle === "closed")
+            return false;
+        const task = this.controlWriteTail.then(async () => {
+            if (this.lifecycle === "closed")
+                return false;
+            await this.writeControl(type, payload);
+            return true;
+        });
+        this.controlWriteTail = task.then(() => undefined, () => undefined);
+        return await task;
+    }
+    sendTerminalControl(reason) {
+        if (this.controlTerminalSealed)
+            return this.controlWriteTail;
+        this.controlTerminalSealed = true;
+        const task = this.controlWriteTail.then(async () => {
+            if (this.lifecycle === "closed")
+                throw this.terminalError ?? new SessionV2Error("closed", "Flowersec v2 session closed");
+            if (!this.sentGoAway) {
+                this.sentGoAway = true;
+                this.sentGoAwayLastAccepted = this.peerLedger.frontier;
+                this.sentGoAwayReason = reason;
+            }
+            await this.writeControl(InnerTypeV2.GoAway, idReason(this.sentGoAwayLastAccepted, this.sentGoAwayReason));
+            if (!this.sentSessionClose) {
+                this.sentSessionClose = true;
+                await this.writeControl(InnerTypeV2.SessionClose, Uint8Array.of(0, reason));
+                this.sessionCloseCommitted = true;
+            }
+            await this.control.closeWrite();
+        });
+        this.controlWriteTail = task.catch(() => undefined);
+        return task;
+    }
+    async writeControl(type, payload, signal) {
+        const inner = encodeInnerRecordV2(type, payload);
+        const roots = this.rootForSend(this.controlSendEpoch);
+        const material = deriveControlMaterial(roots.controlRoot, this.h3, this.sendDirection, this.controlSendEpoch);
+        const header = {
+            epoch: this.controlSendEpoch,
+            sequence: this.controlSendSequence,
+            ciphertextLength: inner.length + 16,
+        };
+        const ciphertext = sealRecord(this.config.suite, material, this.h3, 0n, this.sendDirection, header, inner);
+        this.controlSendSequence += 1n;
+        await writeAll(this.control, concat(encodeRecordHeader(header), ciphertext), signal);
+        this.markAuthenticatedActivity();
+    }
     async readControl() {
         const header = decodeRecordHeader(await this.controlReader.readExactly(24));
         const cutover = header.epoch === this.controlReceiveEpoch + 1 &&
@@ -622,7 +680,7 @@ export class SessionV2 {
                 const record = await this.readControl();
                 switch (record.type) {
                     case InnerTypeV2.Ping:
-                        await this.sendControl(InnerTypeV2.Pong, record.payload);
+                        await this.sendControlResponse(InnerTypeV2.Pong, record.payload);
                         break;
                     case InnerTypeV2.Pong:
                         this.pings.get(readU64(record.payload))?.resolve();
@@ -685,20 +743,10 @@ export class SessionV2 {
         if (this.lifecycle === "closed")
             return;
         const closed = new SessionV2Error("closed", "Flowersec v2 session closed");
+        const terminal = this.sendTerminalControl(1);
         const work = (async () => {
             try {
-                await this.sendGoAway(1);
-            }
-            catch {
-                // A prior GOAWAY boundary must not suppress the close response.
-            }
-            try {
-                if (!this.sentSessionClose) {
-                    this.sentSessionClose = true;
-                    await this.sendControl(InnerTypeV2.SessionClose, Uint8Array.of(0, 1));
-                    this.sessionCloseCommitted = true;
-                    await this.control.closeWrite();
-                }
+                await terminal;
             }
             catch {
                 // Closing is best-effort once the bounded shutdown has started.
@@ -853,7 +901,12 @@ export class SessionV2 {
         }
         const streams = [...this.streams.values()];
         await Promise.all(streams.map(async (stream) => await stream.waitReceiveRekey(transition, nextEpoch, signal)));
-        await raceAbort(this.sendControl(InnerTypeV2.SessionKeyUpdateACK, payload), signal);
+        const acknowledged = await raceAbort(this.sendControlResponse(InnerTypeV2.SessionKeyUpdateACK, payload), signal);
+        if (!acknowledged) {
+            this.pendingReceiveEpoch = undefined;
+            this.cleanupEpochRoots();
+            return;
+        }
         throwIfAborted(signal);
         this.receiveEpoch = nextEpoch;
         this.receiveTransition = transition;
@@ -897,9 +950,10 @@ export class SessionV2 {
         }
     }
     async commitOutboundReset(id) {
-        await this.sendControl(InnerTypeV2.StreamReset, idReason(id, 6));
-        this.outboundLedger.localResetCommitted(id);
-        this.notifyOutboundFrontierChanged();
+        if (await this.sendControlCleanup(InnerTypeV2.StreamReset, idReason(id, 6))) {
+            this.outboundLedger.localResetCommitted(id);
+            this.notifyOutboundFrontierChanged();
+        }
     }
     commitLocalReset(id) {
         if (this.isLocalLogicalID(id)) {
@@ -1026,6 +1080,7 @@ export class SessionV2 {
     fail(error, abortCarrier = true) {
         if (this.lifecycle === "closed")
             return;
+        this.controlTerminalSealed = true;
         this.beginClosing();
         const normalPeerCarrierClose = this.sessionCloseCommitted && error instanceof CarrierError && error.code === "closed";
         if (normalPeerCarrierClose)
@@ -1224,6 +1279,10 @@ class EncryptedStreamV2 {
         if (this.terminalError !== undefined)
             return false;
         this.terminalError = error;
+        const pendingSendRekey = this.pendingSendRekey;
+        this.pendingSendRekey = undefined;
+        pendingSendRekey?.armed.reject(error);
+        pendingSendRekey?.done.reject(error);
         this.opened.reject(error);
         this.data.fail(error);
         return true;

package/dist/v3/admissionError.d.ts

@@ -0,0 +1,4 @@
+export declare class AdmissionSessionV3Error extends Error {
+    readonly reason: string;
+    constructor(reason: string, message: string);
+}

package/dist/v3/admissionError.js

@@ -0,0 +1,8 @@
+export class AdmissionSessionV3Error extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = "AdmissionSessionV3Error";
+    }
+}

package/dist/v3/artifact.d.ts

@@ -0,0 +1,145 @@
+import { FLOWERSEC_V3_PROFILE } from "./transportConstants.js";
+export type ArtifactCarrierV3 = "websocket" | "raw_quic" | "webtransport";
+export type ArtifactPathKindV3 = "direct" | "tunnel";
+export type CertificatePinV3 = Readonly<{
+    algorithm: "sha-256";
+    not_after_unix_s: number;
+    value_b64u: string;
+}>;
+export type TransportSecurityPolicyV3 = Readonly<{
+    mode: "ca";
+}> | Readonly<{
+    mode: "pin";
+    pins: readonly CertificatePinV3[];
+}>;
+export type ArtifactCandidateV3 = Readonly<{
+    id: string;
+    carrier: ArtifactCarrierV3;
+    url: string;
+    wire_profile: string;
+    tls: TransportSecurityPolicyV3;
+    normalized_url?: string;
+}>;
+export type CanonicalArtifactCandidateV3 = Readonly<{
+    carrier: ArtifactCarrierV3;
+    id: string;
+    normalized_url: string;
+    tls: TransportSecurityPolicyV3;
+    wire_profile: string;
+}>;
+export type SessionContractV3 = Readonly<{
+    channel_id: string;
+    init_expire_at_unix_s: number;
+    idle_timeout_seconds: number;
+    establish_timeout_seconds: number;
+    rekey_prepare_timeout_seconds: number;
+    rekey_completion_timeout_seconds: number;
+    max_inbound_streams: number;
+    e2ee_psk_b64u: string;
+    allowed_suites: readonly number[];
+    default_suite: number;
+    selected_features: number;
+    contract_hash_b64u: string;
+}>;
+export type DirectArtifactPathV3 = Readonly<{
+    kind: "direct";
+    rendezvous_group_id: string;
+    listener_audience: string;
+    routing_token: string;
+    candidates: readonly ArtifactCandidateV3[];
+}>;
+export type TunnelArtifactPathV3 = Readonly<{
+    kind: "tunnel";
+    rendezvous_group_id: string;
+    listener_audience: string;
+    role: 1 | 2;
+    local_endpoint_instance_id: string;
+    expected_peer_endpoint_instance_id: string;
+    token: string;
+    candidates: readonly ArtifactCandidateV3[];
+}>;
+export type ScopeMetadataV3 = Readonly<{
+    scope: string;
+    scope_version: number;
+    critical: boolean;
+    payload: Readonly<Record<string, unknown>>;
+}>;
+export type CorrelationTagV3 = Readonly<{
+    key: string;
+    value: string;
+}>;
+export type CorrelationContextV3 = Readonly<{
+    v: 3;
+    tags: readonly CorrelationTagV3[];
+}>;
+export type ArtifactV3 = Readonly<{
+    v: 3;
+    profile: typeof FLOWERSEC_V3_PROFILE;
+    session: SessionContractV3;
+    path: DirectArtifactPathV3 | TunnelArtifactPathV3;
+    scoped: readonly ScopeMetadataV3[];
+    correlation: CorrelationContextV3;
+}>;
+type CommonFSB3RequestV3 = Readonly<{
+    profile: typeof FLOWERSEC_V3_PROFILE;
+    channel_id: string;
+    session_contract_hash_b64u: string;
+    rendezvous_group_id: string;
+    candidates: readonly CanonicalArtifactCandidateV3[];
+    candidate_set_hash_b64u: string;
+    chosen_candidate_id: string;
+    listener_audience: string;
+}>;
+export type DirectFSB3RequestV3 = CommonFSB3RequestV3 & Readonly<{
+    pathKind: "direct";
+    routing_token: string;
+}>;
+export type TunnelFSB3RequestV3 = CommonFSB3RequestV3 & Readonly<{
+    pathKind: "tunnel";
+    role: 1 | 2;
+    endpoint_instance_id: string;
+    attach_token: string;
+}>;
+export type FSB3RequestV3 = DirectFSB3RequestV3 | TunnelFSB3RequestV3;
+export type DecodedFSB3RequestV3 = Readonly<{
+    request: FSB3RequestV3;
+    raw: Uint8Array;
+    localAdmissionBinding: Uint8Array;
+}>;
+export declare enum AdmissionStatusV3 {
+    Success = 0,
+    Reject = 1,
+    Retryable = 2
+}
+export type AdmissionResponseV3 = Readonly<{
+    status: AdmissionStatusV3;
+    reason: string;
+}>;
+export type ArtifactV3ErrorCode = "artifact_too_large" | "fsb3_payload_too_large" | "invalid_artifact" | "invalid_candidate" | "invalid_fsa3" | "invalid_fsb3" | "noncanonical_fsb3";
+export declare class ArtifactV3Error extends Error {
+    readonly code: ArtifactV3ErrorCode;
+    constructor(code: ArtifactV3ErrorCode, message: string);
+}
+export type LabeledHashV3 = Readonly<{
+    canonicalJSON: string;
+    hash: Uint8Array;
+    hashBase64URL: string;
+}>;
+export type CanonicalCandidateSetV3 = LabeledHashV3 & Readonly<{
+    candidates: readonly CanonicalArtifactCandidateV3[];
+}>;
+export declare function computeSessionContractHashV3(session: SessionContractV3): LabeledHashV3;
+export declare function canonicalizeCandidatesV3(kind: ArtifactPathKindV3, candidates: readonly ArtifactCandidateV3[]): CanonicalCandidateSetV3;
+export declare function decodeArtifactV3JSON(raw: string | Uint8Array): ArtifactV3;
+export declare function encodeArtifactV3JSON(artifact: ArtifactV3): Uint8Array;
+export declare function validateArtifactV3(artifact: ArtifactV3): CanonicalCandidateSetV3;
+export declare function buildFSB3RequestV3(artifact: ArtifactV3, chosenCandidateID: string): FSB3RequestV3;
+export declare function encodeFSB3RequestV3(request: FSB3RequestV3): Uint8Array;
+export declare function decodeFSB3RequestV3(raw: Uint8Array): DecodedFSB3RequestV3;
+export declare function admissionBindingV3(rawFSB3: Uint8Array): Uint8Array;
+export declare function acceptorAdmissionsHashV3(framesByCandidateID: ReadonlyMap<string, Uint8Array>): Uint8Array;
+export declare function encodeFSA3ResponseV3(response: AdmissionResponseV3, admissionReasons?: ReadonlySet<string>): Uint8Array;
+export declare function decodeFSA3ResponseV3(raw: Uint8Array): AdmissionResponseV3;
+export declare function tlsPolicyDigestV3(policy: TransportSecurityPolicyV3): LabeledHashV3;
+export declare function activePinsV3(policy: TransportSecurityPolicyV3, attemptNowUnixSeconds: number): readonly CertificatePinV3[];
+export {};