@genation/bridge-peer 0.1.0

package/react-native/native/GenationBridgeCryptoMobile.xcframework/ios-arm64_x86_64-simulator/Headers/module.modulemap

@@ -0,0 +1,7 @@
+module GenationBridgeCryptoMobileFFI {
+    header "GenationBridgeCryptoMobileFFI.h"
+    export *
+    use "Darwin"
+    use "_Builtin_stdbool"
+    use "_Builtin_stdint"
+}

package/react-native.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      android: { sourceDir: "./react-native/android" },
+      ios: { podspecPath: "./GenationBridgePeer.podspec" },
+    },
+  },
+};

package/src/core/codec.d.ts

@@ -0,0 +1,5 @@
+/** Application codec kept above the byte-only E2EE provider. */ export type BridgeCodec<T = unknown> = Readonly<{
+  encode(value: T): Uint8Array;
+  decode(value: Uint8Array): T;
+}>;
+/** Strict default JSON codec with sanitized encode and decode failures. */ export declare const bridgeJsonCodec: BridgeCodec;

package/src/core/codec.js

@@ -0,0 +1,46 @@
+import { BridgePeerError } from "./errors.js";
+const assertJsonNative = (value, seen)=>{
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) return;
+  if (typeof value !== "object") throw new TypeError("unsupported_json_value");
+  if (seen.has(value)) throw new TypeError("cyclic_json_value");
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      if (Object.keys(value).length !== value.length) {
+        throw new TypeError("sparse_json_array");
+      }
+      for (const entry of value)assertJsonNative(entry, seen);
+      return;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new TypeError("non_plain_json_object");
+    }
+    for (const entry of Object.values(value)){
+      assertJsonNative(entry, seen);
+    }
+  } finally{
+    seen.delete(value);
+  }
+};
+/** Strict default JSON codec with sanitized encode and decode failures. */ export const bridgeJsonCodec = Object.freeze({
+  encode (value) {
+    try {
+      assertJsonNative(value, new WeakSet());
+      const json = JSON.stringify(value);
+      if (json === undefined) throw new TypeError("unsupported_json_value");
+      return new TextEncoder().encode(json);
+    } catch  {
+      throw new BridgePeerError("CODEC_ERROR");
+    }
+  },
+  decode (value) {
+    try {
+      return JSON.parse(new TextDecoder("utf-8", {
+        fatal: true
+      }).decode(value));
+    } catch  {
+      throw new BridgePeerError("CODEC_ERROR");
+    }
+  }
+});

package/src/core/errors.d.ts

@@ -0,0 +1,11 @@
+import type { BridgeCode } from "@genation/bridge-contracts";
+/** Stable peer-local or relay-owned error categories exposed by the SDK facade. */ export type BridgePeerErrorCode = BridgeCode | "INVALID_CONFIGURATION" | "PEER_OFFLINE" | "PEER_CLOSED" | "DUPLICATE_CAPABILITY" | "CODEC_ERROR" | "KEYSTORE_ERROR" | "GRANT_FAILED" | "TRANSPORT_ERROR";
+/** Sanitized application-facing error without customer content or provider details. */ export declare class BridgePeerError extends Error {
+  /** Stable machine-readable SDK or Bridge code. */ readonly code: BridgePeerErrorCode;
+  /** Whether an application may consider an explicit retry. */ readonly retryable: boolean;
+  /** Creates one sanitized peer error. */ constructor(code: BridgePeerErrorCode, retryable?: boolean);
+  /** Returns the only fields intended for public diagnostics. */ toJSON(): Readonly<{
+    code: BridgePeerErrorCode;
+    retryable: boolean;
+  }>;
+}

package/src/core/errors.js

@@ -0,0 +1,27 @@
+const localMessages = Object.freeze({
+  INVALID_CONFIGURATION: "Invalid peer configuration",
+  PEER_OFFLINE: "Peer is not connected",
+  PEER_CLOSED: "Peer is closed",
+  DUPLICATE_CAPABILITY: "Capability is already exposed",
+  CODEC_ERROR: "Codec failed",
+  KEYSTORE_ERROR: "Peer identity storage failed",
+  GRANT_FAILED: "Grant acquisition failed",
+  TRANSPORT_ERROR: "Peer transport failed"
+});
+const bridgeMessage = (code)=>code.split("_").map((part)=>part[0] + part.slice(1).toLowerCase()).join(" ");
+/** Sanitized application-facing error without customer content or provider details. */ export class BridgePeerError extends Error {
+  /** Stable machine-readable SDK or Bridge code. */ code;
+  /** Whether an application may consider an explicit retry. */ retryable;
+  /** Creates one sanitized peer error. */ constructor(code, retryable = false){
+    super(code in localMessages ? localMessages[code] : bridgeMessage(code));
+    this.name = "BridgePeerError";
+    this.code = code;
+    this.retryable = retryable;
+  }
+  /** Returns the only fields intended for public diagnostics. */ toJSON() {
+    return Object.freeze({
+      code: this.code,
+      retryable: this.retryable
+    });
+  }
+}

package/src/core/identity.d.ts

@@ -0,0 +1,16 @@
+/** SDK-owned long-term private identity for one exact project and peer pair. */ export type BridgePeerIdentity = Readonly<{
+  connectionPrivateKey: Readonly<{
+    kty: "OKP";
+    crv: "Ed25519";
+    x: string;
+    d: string;
+  }>;
+  noiseStaticPrivateKey: string;
+}>;
+/** Atomic platform-neutral identity storage contract used by peer adapters. */ export type BridgePeerKeyStore = Readonly<{
+  loadOrCreate(input: Readonly<{
+    projectId: string;
+    peerId: string;
+    create(): Promise<BridgePeerIdentity>;
+  }>): Promise<BridgePeerIdentity>;
+}>;

package/src/core/identity.js

@@ -0,0 +1 @@
+/** SDK-owned long-term private identity for one exact project and peer pair. */ 

package/src/core/lifecycle.d.ts

@@ -0,0 +1,4 @@
+/** Internal platform activity source used to suspend live mobile resources. */ export type BridgePeerPlatformLifecycle = Readonly<{
+  readonly active: boolean;
+  subscribe(listener: (active: boolean) => void): () => void;
+}>;

package/src/core/lifecycle.js

@@ -0,0 +1 @@
+/** Internal platform activity source used to suspend live mobile resources. */ 

package/src/core/mod.d.ts

@@ -0,0 +1,6 @@
+export { type BridgeCodec, bridgeJsonCodec } from "./codec.js";
+export { BridgePeerError, type BridgePeerErrorCode } from "./errors.js";
+export { type BridgePeerIdentity, type BridgePeerKeyStore } from "./identity.js";
+export { type BridgePeerPlatformLifecycle } from "./lifecycle.js";
+export { type BridgeExposureContext, type BridgeExposureOptions, type BridgeExposureRegistration, type BridgeFanoutInvocationOptions, type BridgeFanoutResult, type BridgePeer, type BridgePeerConnectResult, type BridgePeerCoreOptions, type BridgePeerReconnectOptions, type BridgePeerState, type BridgeTargetInvocationOptions, createBridgePeerCore } from "./peer.js";
+export { type BridgeGrantProvider, type BridgeGrantProviderInput, type BridgeGrantProviderResult, type BridgePeerPublicIdentity, type BridgePeerRuntime, type BridgePeerRuntimeConnectInput, type BridgePeerRuntimeConnection, type RuntimeExposure, type RuntimeFanoutInput, type RuntimeFanoutResult, type RuntimeInvocationInput, type RuntimeRelayFailure } from "./runtime.js";

package/src/core/mod.js

@@ -0,0 +1,3 @@
+export { bridgeJsonCodec } from "./codec.js";
+export { BridgePeerError } from "./errors.js";
+export { createBridgePeerCore } from "./peer.js";

package/src/core/peer.d.ts

@@ -0,0 +1,67 @@
+import { type BridgeCodec } from "./codec.js";
+import { BridgePeerError } from "./errors.js";
+import type { BridgePeerPlatformLifecycle } from "./lifecycle.js";
+import type { BridgeGrantProvider, BridgePeerRuntime } from "./runtime.js";
+/** Stable observable state of one logical peer object. */ export type BridgePeerState = "idle" | "connecting" | "connected" | "reconnecting" | "suspended" | "closed";
+/** Simple result returned by idempotent connection intent. */ export type BridgePeerConnectResult = Readonly<{
+  status: "connected" | "connecting" | "reconnecting";
+}>;
+/** Tunable bounded reconnect behavior, primarily for deterministic adapters and tests. */ export type BridgePeerReconnectOptions = Readonly<{
+  maxAttempts?: number;
+  delay?: (attempt: number) => Promise<void>;
+}>;
+/** Shared peer options independent of Node.js or React Native adapters. */ export type BridgePeerCoreOptions = Readonly<{
+  projectId: string;
+  peerId: string;
+  grantProvider: BridgeGrantProvider;
+  requestedInvokeCapabilities?: readonly string[];
+  codec?: BridgeCodec;
+  reconnect?: BridgePeerReconnectOptions;
+  lifecycle?: BridgePeerPlatformLifecycle;
+}>;
+/** One capability handler registration retained as desired state until disposal. */ export type BridgeExposureRegistration = Readonly<{
+  dispose(): Promise<void>;
+}>;
+/** Context provided to one application exposure handler. */ export type BridgeExposureContext = Readonly<{
+  signal: AbortSignal;
+}>;
+/** Exposure options selecting response mode and an optional application codec. */ export type BridgeExposureOptions<TInput = unknown, TOutput = unknown> = Readonly<{
+  stream?: boolean;
+  codec?: BridgeCodec<TInput | TOutput>;
+}>;
+/** Invocation options for one explicit target and optional response stream. */ export type BridgeTargetInvocationOptions = Readonly<{
+  targetPeer: string;
+  stream?: boolean;
+  deadlineAt?: number;
+  signal?: AbortSignal;
+  codec?: BridgeCodec;
+}>;
+/** Invocation options for one target-less unary fanout. */ export type BridgeFanoutInvocationOptions = Readonly<{
+  deadlineAt?: number;
+  signal?: AbortSignal;
+  codec?: BridgeCodec;
+}>;
+/** One application-facing all-settled fanout entry. */ export type BridgeFanoutResult<T = unknown> = Readonly<{
+  peerId: string;
+  status: "fulfilled";
+  value: T;
+}> | Readonly<{
+  peerId: string;
+  status: "rejected";
+  error: BridgePeerError;
+}>;
+/** Public symmetric peer facade for exposure, invocation, state, and lifecycle. */ export type BridgePeer = Readonly<{
+  projectId: string;
+  peerId: string;
+  readonly state: BridgePeerState;
+  connect(): Promise<BridgePeerConnectResult>;
+  expose<TInput = unknown, TOutput = unknown>(capability: string, handler: (input: TInput, context: BridgeExposureContext) => TOutput | Response | Promise<TOutput | Response>, options?: BridgeExposureOptions<TInput, TOutput>): BridgeExposureRegistration;
+  invoke<TInput = unknown, TOutput = unknown>(capability: string, input: TInput, options: BridgeTargetInvocationOptions & Readonly<{
+    stream: true;
+  }>): Promise<Response>;
+  invoke<TInput = unknown, TOutput = unknown>(capability: string, input: TInput, options: BridgeTargetInvocationOptions): Promise<TOutput>;
+  invoke<TInput = unknown, TOutput = unknown>(capability: string, input: TInput, options?: BridgeFanoutInvocationOptions): Promise<readonly BridgeFanoutResult<TOutput>[]>;
+  subscribeState(listener: (state: BridgePeerState) => void): () => void;
+  close(): Promise<void>;
+}>;
+/** Creates the shared peer state machine around one selected platform runtime. */ export declare const createBridgePeerCore: (options: BridgePeerCoreOptions, runtime: BridgePeerRuntime) => BridgePeer;

package/src/core/peer.js

@@ -0,0 +1,373 @@
+import { capabilityNameSchema, opaqueIdSchema } from "@genation/bridge-contracts";
+import { bridgeJsonCodec } from "./codec.js";
+import { BridgePeerError } from "./errors.js";
+const defaultReconnectDelay = async (attempt)=>{
+  const base = Math.min(3_000, 100 * 2 ** Math.max(0, attempt - 1));
+  const jittered = Math.round(base * (0.8 + Math.random() * 0.4));
+  await new Promise((resolve)=>setTimeout(resolve, jittered));
+};
+const validateDeadline = (value)=>{
+  const now = Date.now();
+  const deadline = value ?? now + 30_000;
+  if (!Number.isSafeInteger(deadline) || deadline <= now || deadline > now + 120_000) throw new BridgePeerError("DEADLINE_EXCEEDED");
+  return deadline;
+};
+const mapRuntimeError = (error)=>error instanceof BridgePeerError ? error : new BridgePeerError("TRANSPORT_ERROR");
+/** Creates the shared peer state machine around one selected platform runtime. */ export const createBridgePeerCore = (options, runtime)=>{
+  if (!opaqueIdSchema.safeParse(options.projectId).success || !opaqueIdSchema.safeParse(options.peerId).success || typeof options.grantProvider !== "function") throw new BridgePeerError("INVALID_CONFIGURATION");
+  const invokeCapabilities = [
+    ...options.requestedInvokeCapabilities ?? []
+  ];
+  if (invokeCapabilities.some((value)=>!capabilityNameSchema.safeParse(value).success) || new Set(invokeCapabilities).size !== invokeCapabilities.length) throw new BridgePeerError("INVALID_CONFIGURATION");
+  const defaultCodec = options.codec ?? bridgeJsonCodec;
+  const exposures = new Map();
+  const listeners = new Set();
+  const maxReconnectAttempts = options.reconnect?.maxAttempts ?? 5;
+  if (!Number.isSafeInteger(maxReconnectAttempts) || maxReconnectAttempts < 0) {
+    throw new BridgePeerError("INVALID_CONFIGURATION");
+  }
+  const reconnectDelay = options.reconnect?.delay ?? defaultReconnectDelay;
+  let state = "idle";
+  let desiredConnection = false;
+  let connection;
+  let generation = 0;
+  let reconnectPromise;
+  let closePromise;
+  let openingController;
+  let platformActive = options.lifecycle?.active ?? true;
+  let unsubscribeLifecycle;
+  const isClosed = ()=>state === "closed";
+  const transition = (next)=>{
+    if (state === next) return;
+    state = next;
+    for (const listener of [
+      ...listeners
+    ]){
+      try {
+        listener(next);
+      } catch  {
+      // Customer observers cannot own or interrupt SDK lifecycle progress.
+      }
+    }
+  };
+  const snapshot = ()=>Object.freeze([
+      ...exposures.values()
+    ]);
+  const open = async (reconnecting)=>{
+    const currentGeneration = ++generation;
+    const controller = new AbortController();
+    openingController = controller;
+    let candidate;
+    try {
+      candidate = await runtime.connect({
+        projectId: options.projectId,
+        peerId: options.peerId,
+        grantProvider: options.grantProvider,
+        requestedInvokeCapabilities: Object.freeze([
+          ...invokeCapabilities
+        ]),
+        desiredExposures: snapshot,
+        signal: controller.signal,
+        onDisconnect: (error)=>{
+          if (currentGeneration !== generation || state === "closed") return;
+          connection = undefined;
+          if (!desiredConnection) {
+            transition("idle");
+            return;
+          }
+          if (!platformActive) {
+            transition("suspended");
+            return;
+          }
+          transition("reconnecting");
+          reconnectPromise ??= reconnect().finally(()=>{
+            reconnectPromise = undefined;
+          });
+          void error;
+        }
+      });
+      if (currentGeneration !== generation || state === "closed" || !platformActive) {
+        throw new BridgePeerError("PEER_CLOSED");
+      }
+      connection = candidate;
+      await candidate.replaceExposures(snapshot());
+      transition("connected");
+      void reconnecting;
+      return candidate;
+    } catch (error) {
+      if (candidate !== undefined) {
+        if (connection === candidate) connection = undefined;
+        await candidate.close().catch(()=>undefined);
+      }
+      throw error;
+    } finally{
+      if (openingController === controller) openingController = undefined;
+    }
+  };
+  const reconnect = async ()=>{
+    for(let attempt = 1; attempt <= maxReconnectAttempts; attempt += 1){
+      if (!desiredConnection || isClosed() || !platformActive) return;
+      await reconnectDelay(attempt);
+      if (!desiredConnection || isClosed() || !platformActive) return;
+      try {
+        await open(true);
+        return;
+      } catch (error) {
+        if (error instanceof BridgePeerError && error.code === "PEER_CLOSED") return;
+      }
+    }
+    if (state !== "closed") {
+      desiredConnection = false;
+      transition("idle");
+    }
+  };
+  const connect = async ()=>{
+    if (state === "closed") throw new BridgePeerError("PEER_CLOSED");
+    if (state === "connected") return Object.freeze({
+      status: "connected"
+    });
+    if (state === "connecting") return Object.freeze({
+      status: "connecting"
+    });
+    if (state === "reconnecting") {
+      return Object.freeze({
+        status: "reconnecting"
+      });
+    }
+    if (state === "suspended") {
+      desiredConnection = true;
+      return Object.freeze({
+        status: "reconnecting"
+      });
+    }
+    desiredConnection = true;
+    if (!platformActive) {
+      transition("suspended");
+      return Object.freeze({
+        status: "reconnecting"
+      });
+    }
+    transition("connecting");
+    const attemptGeneration = generation + 1;
+    try {
+      await open(false);
+      return Object.freeze({
+        status: "connected"
+      });
+    } catch (error) {
+      if (desiredConnection && !isClosed() && (!platformActive || generation !== attemptGeneration)) {
+        return Object.freeze({
+          status: "reconnecting"
+        });
+      }
+      desiredConnection = false;
+      if (!isClosed()) transition("idle");
+      throw mapRuntimeError(error);
+    }
+  };
+  const assertConnected = ()=>{
+    if (state === "closed") throw new BridgePeerError("PEER_CLOSED");
+    if (state !== "connected" || connection === undefined) {
+      throw new BridgePeerError("PEER_OFFLINE");
+    }
+    return connection;
+  };
+  const recoverExposureReplacement = async (active)=>{
+    if (connection !== active || state !== "connected") return;
+    connection = undefined;
+    generation += 1;
+    await active.close().catch(()=>undefined);
+    if (!desiredConnection || isClosed()) return;
+    transition("reconnecting");
+    reconnectPromise ??= reconnect().finally(()=>{
+      reconnectPromise = undefined;
+    });
+  };
+  const expose = (capability, handler, exposureOptions)=>{
+    if (state === "closed") throw new BridgePeerError("PEER_CLOSED");
+    if (!capabilityNameSchema.safeParse(capability).success) {
+      throw new BridgePeerError("INVALID_CONFIGURATION");
+    }
+    if (exposures.has(capability)) {
+      throw new BridgePeerError("DUPLICATE_CAPABILITY");
+    }
+    const codec = exposureOptions?.codec ?? defaultCodec;
+    const stream = exposureOptions?.stream ?? false;
+    const exposure = Object.freeze({
+      capability,
+      stream,
+      handle: async (payload, signal)=>{
+        let input;
+        try {
+          input = codec.decode(payload);
+        } catch  {
+          throw new BridgePeerError("CODEC_ERROR");
+        }
+        let output;
+        try {
+          output = await handler(input, Object.freeze({
+            signal
+          }));
+        } catch (error) {
+          if (error instanceof BridgePeerError) throw error;
+          throw new BridgePeerError("EXPOSER_ERROR");
+        }
+        if (stream) {
+          if (!(output instanceof Response)) {
+            throw new BridgePeerError("EXPOSER_ERROR");
+          }
+          return output;
+        }
+        if (output instanceof Response) throw new BridgePeerError("EXPOSER_ERROR");
+        try {
+          return codec.encode(output);
+        } catch  {
+          throw new BridgePeerError("CODEC_ERROR");
+        }
+      }
+    });
+    exposures.set(capability, exposure);
+    if (connection !== undefined && state === "connected") {
+      const active = connection;
+      void active.replaceExposures(snapshot()).catch(()=>recoverExposureReplacement(active));
+    }
+    let disposed = false;
+    return Object.freeze({
+      dispose: async ()=>{
+        if (disposed) return;
+        disposed = true;
+        exposures.delete(capability);
+        if (connection !== undefined && state === "connected") {
+          const active = connection;
+          await active.replaceExposures(snapshot()).catch(()=>recoverExposureReplacement(active));
+        }
+      }
+    });
+  };
+  const invoke = async (capability, input, invokeOptions)=>{
+    const active = assertConnected();
+    if (!capabilityNameSchema.safeParse(capability).success) {
+      throw new BridgePeerError("INVALID_CONFIGURATION");
+    }
+    const deadlineAt = validateDeadline(invokeOptions?.deadlineAt);
+    if (invokeOptions?.signal?.aborted) throw new BridgePeerError("CANCELLED");
+    const codec = invokeOptions?.codec ?? defaultCodec;
+    let payload;
+    try {
+      payload = codec.encode(input);
+    } catch  {
+      throw new BridgePeerError("CODEC_ERROR");
+    }
+    try {
+      if ("targetPeer" in (invokeOptions ?? {})) {
+        const target = invokeOptions.targetPeer;
+        if (!opaqueIdSchema.safeParse(target).success) {
+          throw new BridgePeerError("INVALID_CONFIGURATION");
+        }
+        const direct = {
+          capability,
+          payload,
+          targetPeer: target,
+          deadlineAt,
+          signal: invokeOptions?.signal
+        };
+        if (invokeOptions.stream === true) {
+          return await active.invokeStream(direct);
+        }
+        return codec.decode(await active.invokeUnary(direct));
+      }
+      if (invokeOptions?.stream === true) {
+        throw new BridgePeerError("INVALID_CONFIGURATION");
+      }
+      const fanout = await active.invokeFanout({
+        capability,
+        payload,
+        deadlineAt,
+        signal: invokeOptions?.signal
+      });
+      return fanout.map((result)=>{
+        if (result.status === "rejected") return Object.freeze({
+          ...result
+        });
+        try {
+          return Object.freeze({
+            peerId: result.peerId,
+            status: "fulfilled",
+            value: codec.decode(result.payload)
+          });
+        } catch  {
+          return Object.freeze({
+            peerId: result.peerId,
+            status: "rejected",
+            error: new BridgePeerError("CODEC_ERROR")
+          });
+        }
+      });
+    } catch (error) {
+      throw mapRuntimeError(error);
+    }
+  };
+  const close = ()=>{
+    closePromise ??= (async ()=>{
+      if (state === "closed") return;
+      desiredConnection = false;
+      generation += 1;
+      openingController?.abort();
+      openingController = undefined;
+      unsubscribeLifecycle?.();
+      unsubscribeLifecycle = undefined;
+      const active = connection;
+      connection = undefined;
+      transition("closed");
+      await active?.close().catch(()=>undefined);
+      listeners.clear();
+    })();
+    return closePromise;
+  };
+  if (options.lifecycle !== undefined) {
+    unsubscribeLifecycle = options.lifecycle.subscribe((active)=>{
+      if (platformActive === active || isClosed()) return;
+      platformActive = active;
+      if (!active) {
+        generation += 1;
+        openingController?.abort();
+        openingController = undefined;
+        const live = connection;
+        connection = undefined;
+        transition("suspended");
+        void live?.close().catch(()=>undefined);
+        return;
+      }
+      if (!desiredConnection) {
+        transition("idle");
+        return;
+      }
+      transition("reconnecting");
+      reconnectPromise ??= reconnect().finally(()=>{
+        reconnectPromise = undefined;
+      });
+    });
+    if (!platformActive) transition("suspended");
+  }
+  const peer = {
+    projectId: options.projectId,
+    peerId: options.peerId,
+    get state () {
+      return state;
+    },
+    connect,
+    expose,
+    invoke: invoke,
+    subscribeState: (listener)=>{
+      listeners.add(listener);
+      try {
+        listener(state);
+      } catch  {
+      // Initial observation follows the same isolation rule as later transitions.
+      }
+      return ()=>listeners.delete(listener);
+    },
+    close
+  };
+  return Object.freeze(peer);
+};

package/src/core/runtime.d.ts

@@ -0,0 +1,78 @@
+import type { BridgeCode } from "@genation/bridge-contracts";
+import type { BridgePeerError } from "./errors.js";
+/** Public identity supplied to the customer grant provider without private keys. */ export type BridgePeerPublicIdentity = Readonly<{
+  connectionPublicKey: Readonly<{
+    kty: "OKP";
+    crv: "Ed25519";
+    x: string;
+  }>;
+  noiseStaticPublicKey: Readonly<{
+    kty: "OKP";
+    crv: "X25519";
+    x: string;
+  }>;
+}>;
+/** Immutable input used by customer code to obtain one fresh signed peer grant. */ export type BridgeGrantProviderInput = Readonly<{
+  projectId: string;
+  peerId: string;
+  connectionPublicKey: BridgePeerPublicIdentity["connectionPublicKey"];
+  noiseStaticPublicKey: BridgePeerPublicIdentity["noiseStaticPublicKey"];
+  requestedPermissions: Readonly<{
+    expose: readonly string[];
+    invoke: readonly string[];
+  }>;
+}>;
+/** Fresh compact grant returned by a customer-owned backend callback. */ export type BridgeGrantProviderResult = Readonly<{
+  grant: string;
+}>;
+/** Customer callback that authenticates and authorizes peer intent outside Bridge. */ export type BridgeGrantProvider = (input: BridgeGrantProviderInput) => Promise<BridgeGrantProviderResult>;
+/** One desired capability translated to the platform runtime's byte boundary. */ export type RuntimeExposure = Readonly<{
+  capability: string;
+  stream: boolean;
+  handle(payload: Uint8Array, signal: AbortSignal): Promise<Uint8Array | Response>;
+}>;
+/** Direct invocation routed by one connected platform runtime. */ export type RuntimeInvocationInput = Readonly<{
+  capability: string;
+  payload: Uint8Array;
+  targetPeer: string;
+  deadlineAt: number;
+  signal?: AbortSignal;
+}>;
+/** Target-less unary invocation routed as one bounded immutable fanout snapshot. */ export type RuntimeFanoutInput = Readonly<{
+  capability: string;
+  payload: Uint8Array;
+  deadlineAt: number;
+  signal?: AbortSignal;
+}>;
+/** One terminal runtime fanout entry before application decoding. */ export type RuntimeFanoutResult = Readonly<{
+  peerId: string;
+  status: "fulfilled";
+  payload: Uint8Array;
+}> | Readonly<{
+  peerId: string;
+  status: "rejected";
+  error: BridgePeerError;
+}>;
+/** One live platform connection used only through the shared peer state machine. */ export type BridgePeerRuntimeConnection = Readonly<{
+  replaceExposures(exposures: readonly RuntimeExposure[]): Promise<void>;
+  invokeUnary(input: RuntimeInvocationInput): Promise<Uint8Array>;
+  invokeStream(input: RuntimeInvocationInput): Promise<Response>;
+  invokeFanout(input: RuntimeFanoutInput): Promise<readonly RuntimeFanoutResult[]>;
+  close(): Promise<void>;
+}>;
+/** Connection request passed from shared lifecycle state into a platform adapter. */ export type BridgePeerRuntimeConnectInput = Readonly<{
+  projectId: string;
+  peerId: string;
+  grantProvider: BridgeGrantProvider;
+  requestedInvokeCapabilities: readonly string[];
+  desiredExposures(): readonly RuntimeExposure[];
+  signal: AbortSignal;
+  onDisconnect(error: BridgePeerError): void;
+}>;
+/** Platform adapter capable of creating one fresh fenced physical connection. */ export type BridgePeerRuntime = Readonly<{
+  connect(input: BridgePeerRuntimeConnectInput): Promise<BridgePeerRuntimeConnection>;
+}>;
+/** Relay error metadata retained by a platform adapter before SDK error mapping. */ export type RuntimeRelayFailure = Readonly<{
+  bridgeCode: BridgeCode;
+  retryable: boolean;
+}>;