@floegence/flowersec-core 2.5.4 → 3.0.0

package/dist/node/runtimeAuthorizationV3.d.ts

@@ -0,0 +1,29 @@
+import { type ArtifactHandleV3 } from "../v3/publicApi.js";
+/** Opaque, secret-free authorization lookup for one observed FSB3 request. */
+export declare class RuntimeAuthorizationRequestV3 {
+    #private;
+    private constructor();
+    /** Returns the non-secret credential digest used to locate authorization state. */
+    lookupKey(): string;
+    toString(): string;
+    toJSON(): Readonly<Record<string, never>>;
+}
+/**
+ * Opaque, secret-free proof that a tunnel authorization record exactly matched
+ * one observed FSB3 request.
+ */
+export declare class TunnelAuthorizationGrantV3 {
+    private readonly tunnelAuthorizationGrantBrand;
+    private constructor();
+    toString(): string;
+    toJSON(): Readonly<Record<string, never>>;
+}
+export type TunnelAuthorizationGrantOptionsV3 = Readonly<{
+    leaseId: string;
+    allowReplacement?: boolean;
+}>;
+/**
+ * Verifies a trusted authorization artifact against the complete observed FSB3
+ * and mints a request-bound grant that contains no artifact secrets.
+ */
+export declare function verifyTunnelAuthorizationGrantV3(request: RuntimeAuthorizationRequestV3, artifactHandle: ArtifactHandleV3, options: TunnelAuthorizationGrantOptionsV3): TunnelAuthorizationGrantV3;

package/dist/node/runtimeAuthorizationV3.js

@@ -0,0 +1,126 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { buildFSB3RequestV3, encodeFSB3RequestV3, } from "../v3/artifact.js";
+import { unwrapArtifactHandleV3, } from "../v3/publicApi.js";
+const ID = /^[A-Za-z0-9._~-]{1,128}$/u;
+const requests = new WeakMap();
+/** Opaque, secret-free authorization lookup for one observed FSB3 request. */
+export class RuntimeAuthorizationRequestV3 {
+    #lookupKey;
+    constructor(lookupKey) {
+        this.#lookupKey = lookupKey;
+    }
+    /** Returns the non-secret credential digest used to locate authorization state. */
+    lookupKey() { return this.#lookupKey; }
+    toString() { return "Flowersec.RuntimeAuthorizationRequestV3"; }
+    toJSON() { return Object.freeze({}); }
+    /** @internal */
+    static fromDecoded(decoded) {
+        const credential = decoded.request.pathKind === "direct"
+            ? decoded.request.routing_token
+            : decoded.request.attach_token;
+        const lookupKey = createHash("sha256").update(credential, "utf8").digest("base64url");
+        const request = new RuntimeAuthorizationRequestV3(lookupKey);
+        requests.set(request, Object.freeze({
+            lookupKey,
+            decoded,
+            requestDigest: createHash("sha256").update(decoded.raw).digest(),
+        }));
+        Object.freeze(request);
+        return request;
+    }
+}
+/**
+ * Opaque, secret-free proof that a tunnel authorization record exactly matched
+ * one observed FSB3 request.
+ */
+export class TunnelAuthorizationGrantV3 {
+    constructor() { }
+    toString() { return "Flowersec.TunnelAuthorizationGrantV3"; }
+    toJSON() { return Object.freeze({}); }
+}
+const grants = new WeakMap();
+/**
+ * Verifies a trusted authorization artifact against the complete observed FSB3
+ * and mints a request-bound grant that contains no artifact secrets.
+ */
+export function verifyTunnelAuthorizationGrantV3(request, artifactHandle, options) {
+    const observed = requests.get(request);
+    if (observed === undefined || typeof options !== "object" || options === null ||
+        !ID.test(options.leaseId) ||
+        (options.allowReplacement !== undefined && typeof options.allowReplacement !== "boolean")) {
+        throw invalidAuthorization();
+    }
+    try {
+        const artifact = unwrapArtifactHandleV3(artifactHandle);
+        const received = observed.decoded.request;
+        if (artifact.path.kind !== "tunnel" || received.pathKind !== "tunnel" ||
+            artifact.session.init_expire_at_unix_s <= Math.floor(Date.now() / 1_000) ||
+            artifact.path.expected_peer_endpoint_instance_id === received.endpoint_instance_id) {
+            throw invalidAuthorization();
+        }
+        const expected = encodeFSB3RequestV3(buildFSB3RequestV3(artifact, received.chosen_candidate_id));
+        if (!constantTimeEqual(expected, observed.decoded.raw))
+            throw invalidAuthorization();
+        const grant = new TunnelAuthorizationGrantV3();
+        grants.set(grant, {
+            claims: Object.freeze({
+                requestDigest: observed.requestDigest.slice(),
+                credentialId: observed.lookupKey,
+                leaseId: options.leaseId,
+                expiresAtUnixSeconds: artifact.session.init_expire_at_unix_s,
+                expectedPeerEndpointInstanceId: artifact.path.expected_peer_endpoint_instance_id,
+                allowReplacement: options.allowReplacement === true,
+            }),
+            consumed: false,
+        });
+        return Object.freeze(grant);
+    }
+    catch (error) {
+        if (error instanceof TypeError && error.message === "invalid Flowersec tunnel authorization") {
+            throw error;
+        }
+        throw invalidAuthorization();
+    }
+}
+/** @internal */
+export function inspectTunnelAuthorizationGrantV3(grant) {
+    return grants.get(grant)?.claims;
+}
+/** @internal */
+export function validateTunnelAuthorizationGrantV3(grant, request) {
+    const record = grants.get(grant);
+    const claims = record?.claims;
+    const observed = requests.get(request);
+    if (record?.consumed !== false || claims === undefined || observed === undefined ||
+        claims.credentialId !== observed.lookupKey ||
+        !constantTimeEqual(claims.requestDigest, observed.requestDigest))
+        return undefined;
+    return claims;
+}
+/** @internal */
+export function consumeTunnelAuthorizationGrantV3(grant, request) {
+    const claims = validateTunnelAuthorizationGrantV3(grant, request);
+    const record = grants.get(grant);
+    if (claims === undefined || record === undefined)
+        return undefined;
+    record.consumed = true;
+    return claims;
+}
+/** @internal */
+export function retireTunnelAuthorizationGrantV3(grant) {
+    const record = grants.get(grant);
+    if (record === undefined || record.consumed)
+        return undefined;
+    record.consumed = true;
+    return record.claims;
+}
+/** @internal */
+export function runtimeAuthorizationRequestV3FromDecoded(decoded) {
+    return RuntimeAuthorizationRequestV3.fromDecoded(decoded);
+}
+function constantTimeEqual(left, right) {
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+function invalidAuthorization() {
+    return new TypeError("invalid Flowersec tunnel authorization");
+}

package/dist/node/tunnelRuntimeV3.d.ts

@@ -0,0 +1,57 @@
+import { type ReceivedSessionAdmissionV3 } from "../v3/serverAdmission.js";
+import type { CarrierStreamV3 } from "../v3/carrier.js";
+import type { OperationOptions } from "../public/contract.js";
+import { type RuntimeAuthorizationRequestV3, type TunnelAuthorizationGrantV3 } from "./runtimeAuthorizationV3.js";
+export type TunnelAuthorizationDecisionV3 = Readonly<{
+    decision: "allow";
+    grant: TunnelAuthorizationGrantV3;
+}> | Readonly<{
+    decision: "reject" | "retry";
+    reason: string;
+}>;
+export type TunnelRuntimeListenerV3 = Readonly<{
+    carrier: "websocket";
+    host: string;
+    port: number;
+    tls: Readonly<{
+        certificate: string;
+        privateKey: string;
+    }>;
+    allowedOrigins: readonly string[];
+}> | Readonly<{
+    carrier: "raw_quic";
+    host: string;
+    port: number;
+    tls: Readonly<{
+        certificate: string | Uint8Array;
+        privateKey: string | Uint8Array;
+    }>;
+}>;
+export type TunnelRuntimeOptionsV3 = Readonly<{
+    listeners: readonly TunnelRuntimeListenerV3[];
+    maxInboundStreams: number;
+    maxPendingLegs?: number;
+    maxActivePairs?: number;
+    maxConcurrentStreams?: number;
+    maxConcurrentAdmissions?: number;
+    pairTimeoutMs?: number;
+    admissionTimeoutMs?: number;
+    cleanupTimeoutMs?: number;
+    admissionReasons?: readonly string[];
+    authorize(request: RuntimeAuthorizationRequestV3, options: OperationOptions): Promise<TunnelAuthorizationDecisionV3>;
+    release?(leaseId: string, options: Readonly<{
+        signal: AbortSignal;
+    }>): Promise<void> | void;
+}>;
+export declare class TunnelRuntimeV3 {
+    private constructor();
+    start(): Promise<void>;
+    addresses(): readonly Readonly<{
+        host: string;
+        port: number;
+    }>[];
+    close(): Promise<void>;
+}
+export declare function createTunnelRuntimeV3(options: TunnelRuntimeOptionsV3): TunnelRuntimeV3;
+export declare function spliceTunnelStreamsV3(left: CarrierStreamV3, right: CarrierStreamV3, signal: AbortSignal, halfCloseGraceMs?: number): Promise<void>;
+export declare function respondTunnelPairAdmissionsV3(first: ReceivedSessionAdmissionV3, second: ReceivedSessionAdmissionV3, signal: AbortSignal, timeoutMs: number): Promise<void>;