@genation/bridge-peer 0.1.0

package/src/node/file-key-store.js

@@ -0,0 +1,111 @@
+import { chmod, mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { z } from "zod";
+import { ed25519PrivateSigningJwkSchema, opaqueIdSchema } from "@genation/bridge-contracts";
+import { BridgePeerError } from "../core/mod.js";
+const identitySchema = z.object({
+  connectionPrivateKey: ed25519PrivateSigningJwkSchema,
+  noiseStaticPrivateKey: z.string().length(43).regex(/^[A-Za-z0-9_-]{43}$/)
+}).strict();
+const encodeBase64url = (value)=>btoa(String.fromCharCode(...value)).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+const identityName = async (projectId, peerId)=>{
+  const bytes = new TextEncoder().encode(`${projectId.length}:${projectId}${peerId.length}:${peerId}`);
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", Uint8Array.from(bytes).buffer));
+  return encodeBase64url(digest);
+};
+const parseIdentity = (value)=>{
+  try {
+    const parsed = identitySchema.parse(JSON.parse(value));
+    return Object.freeze({
+      connectionPrivateKey: Object.freeze({
+        ...parsed.connectionPrivateKey
+      }),
+      noiseStaticPrivateKey: parsed.noiseStaticPrivateKey
+    });
+  } catch  {
+    throw new BridgePeerError("KEYSTORE_ERROR");
+  }
+};
+const hasCode = (error, code)=>error instanceof Error && "code" in error && error.code === code;
+const readExisting = async (path)=>{
+  try {
+    const value = await readFile(path, "utf8");
+    await chmod(path, 0o600);
+    return parseIdentity(value);
+  } catch (error) {
+    if (hasCode(error, "ENOENT")) return undefined;
+    if (error instanceof BridgePeerError) throw error;
+    throw new BridgePeerError("KEYSTORE_ERROR");
+  }
+};
+const waitForIdentity = async (path, deadline)=>{
+  while(Date.now() < deadline){
+    const existing = await readExisting(path);
+    if (existing !== undefined) return existing;
+    await new Promise((resolve)=>setTimeout(resolve, 10));
+  }
+  throw new BridgePeerError("KEYSTORE_ERROR");
+};
+/** Creates the SDK-managed atomic owner-only Node.js and Electron file key store. */ export const createNodeFileKeyStore = (options = {})=>{
+  const directory = options.directory ?? join(homedir(), ".genation", "bridge", "peers");
+  const lockTimeoutMs = options.lockTimeoutMs ?? 5_000;
+  if (directory.length === 0 || !Number.isSafeInteger(lockTimeoutMs) || lockTimeoutMs <= 0) throw new BridgePeerError("INVALID_CONFIGURATION");
+  return Object.freeze({
+    loadOrCreate: async (input)=>{
+      if (!opaqueIdSchema.safeParse(input.projectId).success || !opaqueIdSchema.safeParse(input.peerId).success) throw new BridgePeerError("KEYSTORE_ERROR");
+      try {
+        await mkdir(directory, {
+          recursive: true,
+          mode: 0o700
+        });
+        await chmod(directory, 0o700);
+        const name = await identityName(input.projectId, input.peerId);
+        const path = join(directory, `${name}.json`);
+        const existing = await readExisting(path);
+        if (existing !== undefined) return existing;
+        const lockPath = join(directory, `${name}.lock`);
+        let lock;
+        try {
+          lock = await open(lockPath, "wx", 0o600);
+        } catch (error) {
+          if (hasCode(error, "EEXIST")) {
+            return await waitForIdentity(path, Date.now() + lockTimeoutMs);
+          }
+          throw error;
+        }
+        let temporary;
+        try {
+          const afterLock = await readExisting(path);
+          if (afterLock !== undefined) return afterLock;
+          const created = parseIdentity(JSON.stringify(await input.create()));
+          temporary = join(directory, `${name}.${crypto.randomUUID()}.tmp`);
+          const file = await open(temporary, "wx", 0o600);
+          try {
+            await file.writeFile(JSON.stringify(created), "utf8");
+            await file.sync();
+          } finally{
+            await file.close();
+          }
+          await chmod(temporary, 0o600);
+          await rename(temporary, path);
+          await chmod(path, 0o600);
+          return created;
+        } finally{
+          if (temporary !== undefined) {
+            await rm(temporary, {
+              force: true
+            }).catch(()=>undefined);
+          }
+          await lock.close().catch(()=>undefined);
+          await rm(lockPath, {
+            force: true
+          }).catch(()=>undefined);
+        }
+      } catch (error) {
+        if (error instanceof BridgePeerError) throw error;
+        throw new BridgePeerError("KEYSTORE_ERROR");
+      }
+    }
+  });
+};

package/src/node/identity-provider.d.ts

@@ -0,0 +1,8 @@
+import type { BridgeE2eeProvider } from "@genation/bridge-contracts/sdk";
+import type { BridgePeerKeyStore } from "../core/mod.js";
+import type { BridgeRelayIdentityProvider } from "../relay/identity.js";
+/** Node identity-provider dependencies retained outside shared relay orchestration. */ export type NodeRelayIdentityProviderOptions = Readonly<{
+  keyStore: BridgePeerKeyStore;
+  e2eeProvider?: () => Promise<BridgeE2eeProvider>;
+}>;
+/** Creates the Node file/JWK/WASM implementation of the opaque relay identity port. */ export declare const createNodeRelayIdentityProvider: (options: NodeRelayIdentityProviderOptions) => BridgeRelayIdentityProvider;

package/src/node/identity-provider.js

@@ -0,0 +1,57 @@
+import { loadBridgeE2eeProvider } from "./crypto-core/javascript/provider.js";
+import { CompactSign, importJWK } from "jose";
+import { decodeBase64url, encodeBase64url } from "../relay/encoding.js";
+import { BridgePeerError } from "../core/mod.js";
+import { createPeerIdentity, derivePeerPublicIdentity } from "./identity.js";
+const encoder = new TextEncoder();
+const signConnectionProof = async (input, privateJwk)=>{
+  try {
+    const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(input.grant)));
+    const now = Math.floor(Date.now() / 1_000);
+    const key = await importJWK(privateJwk, "EdDSA");
+    return await new CompactSign(encoder.encode(JSON.stringify({
+      version: "proof.v1",
+      projectId: input.projectId,
+      peerId: input.peerId,
+      connectionId: input.connectionId,
+      challenge: input.challenge,
+      grantSha256: encodeBase64url(digest),
+      issuedAt: now,
+      expiresAt: Math.min(now + 15, Math.floor(input.challengeExpiresAt / 1_000))
+    }))).setProtectedHeader({
+      alg: "EdDSA"
+    }).sign(key);
+  } catch  {
+    throw new BridgePeerError("GRANT_FAILED");
+  }
+};
+/** Creates the Node file/JWK/WASM implementation of the opaque relay identity port. */ export const createNodeRelayIdentityProvider = (options)=>{
+  const loadProvider = options.e2eeProvider ?? loadBridgeE2eeProvider;
+  let providerPromise;
+  return Object.freeze({
+    load: async (projectId, peerId)=>{
+      const [identity, provider] = await Promise.all([
+        options.keyStore.loadOrCreate({
+          projectId,
+          peerId,
+          create: createPeerIdentity
+        }),
+        providerPromise ??= loadProvider()
+      ]);
+      const publicIdentity = derivePeerPublicIdentity(identity, provider);
+      const localPrivateKey = decodeBase64url(identity.noiseStaticPrivateKey);
+      return Object.freeze({
+        publicIdentity,
+        signConnectionProof: (input)=>signConnectionProof(input, identity.connectionPrivateKey),
+        createInitiator: (input)=>provider.createInitiator({
+            ...input,
+            localPrivateKey
+          }),
+        createResponder: (input)=>provider.createResponder({
+            ...input,
+            localPrivateKey
+          })
+      });
+    }
+  });
+};

package/src/node/identity.js

@@ -0,0 +1,45 @@
+import { ed25519PrivateSigningJwkSchema } from "@genation/bridge-contracts";
+import { exportJWK } from "jose";
+import { BridgePeerError } from "../core/mod.js";
+import { decodeBase64url, encodeBase64url } from "./encoding.js";
+/** Generates one complete persistent peer identity using Web Crypto randomness. */ export const createPeerIdentity = async ()=>{
+  try {
+    const pair = await crypto.subtle.generateKey({
+      name: "Ed25519"
+    }, true, [
+      "sign",
+      "verify"
+    ]);
+    const privateJwk = ed25519PrivateSigningJwkSchema.parse(await exportJWK(pair.privateKey));
+    const noiseStaticPrivateKey = encodeBase64url(crypto.getRandomValues(new Uint8Array(32)));
+    return Object.freeze({
+      connectionPrivateKey: Object.freeze({
+        ...privateJwk
+      }),
+      noiseStaticPrivateKey
+    });
+  } catch  {
+    throw new BridgePeerError("KEYSTORE_ERROR");
+  }
+};
+/** Derives only public grant input from one validated local private identity. */ export const derivePeerPublicIdentity = (identity, e2ee)=>{
+  try {
+    const privateKey = ed25519PrivateSigningJwkSchema.parse(identity.connectionPrivateKey);
+    const noisePrivate = decodeBase64url(identity.noiseStaticPrivateKey);
+    if (noisePrivate.length !== 32) throw new Error("invalid_noise_key");
+    return Object.freeze({
+      connectionPublicKey: Object.freeze({
+        kty: "OKP",
+        crv: "Ed25519",
+        x: privateKey.x
+      }),
+      noiseStaticPublicKey: Object.freeze({
+        kty: "OKP",
+        crv: "X25519",
+        x: encodeBase64url(e2ee.deriveStaticPublic(noisePrivate))
+      })
+    });
+  } catch  {
+    throw new BridgePeerError("KEYSTORE_ERROR");
+  }
+};

package/src/node/mod.d.ts

@@ -0,0 +1,16 @@
+import { type BridgePeer, type BridgePeerCoreOptions, type BridgePeerKeyStore } from "../core/mod.js";
+import { type NodeFileKeyStoreOptions } from "./file-key-store.js";
+import { type NodeRelayRuntimeOptions } from "./relay-runtime.js";
+/** Default managed relay endpoint used by the Node.js happy path. */ export declare const defaultBridgeRelayUrl: "wss://relay.genation.com/v1/relay";
+/** Node.js and Electron peer options layered on the shared public facade. */ export type BridgePeerOptions = BridgePeerCoreOptions & Readonly<{
+  relayUrl?: string;
+  keyStore?: BridgePeerKeyStore;
+  fileKeyStore?: NodeFileKeyStoreOptions;
+  reconnect?: BridgePeerCoreOptions["reconnect"];
+  runtime?: Omit<NodeRelayRuntimeOptions, "relayUrl" | "keyStore">;
+}>;
+/** Creates one Node.js or Electron-main peer with SDK-managed platform defaults. */ export declare const createBridgePeer: (options: BridgePeerOptions) => BridgePeer;
+export * from "../core/mod.js";
+export { createNodeFileKeyStore, type NodeFileKeyStoreOptions } from "./file-key-store.js";
+export { createNodeRelayIdentityProvider, type NodeRelayIdentityProviderOptions } from "./identity-provider.js";
+export { createNodeRelayRuntime, type NodeRelayRuntimeOptions } from "./relay-runtime.js";

package/src/node/mod.js

@@ -0,0 +1,17 @@
+import { createBridgePeerCore } from "../core/mod.js";
+import { createNodeFileKeyStore } from "./file-key-store.js";
+import { createNodeRelayRuntime } from "./relay-runtime.js";
+/** Default managed relay endpoint used by the Node.js happy path. */ export const defaultBridgeRelayUrl = "wss://relay.genation.com/v1/relay";
+/** Creates one Node.js or Electron-main peer with SDK-managed platform defaults. */ export const createBridgePeer = (options)=>{
+  const keyStore = options.keyStore ?? createNodeFileKeyStore(options.fileKeyStore);
+  const runtime = createNodeRelayRuntime({
+    relayUrl: options.relayUrl ?? defaultBridgeRelayUrl,
+    keyStore,
+    ...options.runtime
+  });
+  return createBridgePeerCore(options, runtime);
+};
+export * from "../core/mod.js";
+export { createNodeFileKeyStore } from "./file-key-store.js";
+export { createNodeRelayIdentityProvider } from "./identity-provider.js";
+export { createNodeRelayRuntime } from "./relay-runtime.js";

package/src/node/relay-runtime.d.ts

@@ -0,0 +1,11 @@
+import type { BridgeE2eeProvider } from "@genation/bridge-contracts/sdk";
+import type { BridgePeerKeyStore, BridgePeerRuntime } from "../core/mod.js";
+import { type BridgeRelayRuntimeOptions } from "../relay/runtime.js";
+/** Node relay dependencies selected without runtime platform detection. */ export type NodeRelayRuntimeOptions = Readonly<{
+  relayUrl: string;
+  keyStore: BridgePeerKeyStore;
+  webSocketFactory?: BridgeRelayRuntimeOptions["webSocketFactory"];
+  e2eeProvider?: () => Promise<BridgeE2eeProvider>;
+  operationTimeoutMs?: number;
+}>;
+/** Creates the normative Node relay runtime around file storage and shared E2EE. */ export declare const createNodeRelayRuntime: (options: NodeRelayRuntimeOptions) => BridgePeerRuntime;

package/src/node/relay-runtime.js

@@ -0,0 +1,11 @@
+import { createRelayRuntime } from "../relay/runtime.js";
+import { createNodeRelayIdentityProvider } from "./identity-provider.js";
+/** Creates the normative Node relay runtime around file storage and shared E2EE. */ export const createNodeRelayRuntime = (options)=>createRelayRuntime({
+    relayUrl: options.relayUrl,
+    identityProvider: createNodeRelayIdentityProvider({
+      keyStore: options.keyStore,
+      e2eeProvider: options.e2eeProvider
+    }),
+    webSocketFactory: options.webSocketFactory,
+    operationTimeoutMs: options.operationTimeoutMs
+  });

package/src/react-native/identity-provider.d.ts

@@ -0,0 +1,4 @@
+import type { BridgeRelayIdentityProvider } from "../relay/identity.js";
+import type { GenationBridgeNativeModule } from "./native-module.js";
+export type { GenationBridgeNativeModule } from "./native-module.js";
+/** Adapts secure native identity handles to the shared relay identity port. */ export declare const createReactNativeIdentityProvider: (module: GenationBridgeNativeModule) => BridgeRelayIdentityProvider;

package/src/react-native/identity-provider.js

@@ -0,0 +1,125 @@
+import { BridgePeerError } from "../core/mod.js";
+import { decodeBase64url, encodeBase64url } from "../relay/encoding.js";
+const keyPattern = /^[A-Za-z0-9_-]{43}$/;
+const handlePattern = /^[A-Za-z0-9._:-]{1,512}$/;
+const transportFailure = ()=>new BridgePeerError("TRANSPORT_ERROR");
+const createInitiator = (module, identityHandle, input)=>{
+  let handle;
+  try {
+    handle = module.createInitiator(identityHandle, encodeBase64url(input.prologue), encodeBase64url(input.responderPublicKey));
+    if (!handlePattern.test(handle)) throw new Error("invalid_handle");
+  } catch  {
+    throw transportFailure();
+  }
+  let closed = false;
+  const use = (operation)=>{
+    if (closed) throw transportFailure();
+    try {
+      return operation();
+    } catch  {
+      closed = true;
+      try {
+        module.closeSession(handle);
+      } catch  {
+      // The application never receives provider-specific native cleanup details.
+      }
+      throw transportFailure();
+    }
+  };
+  const session = {
+    beginHandshake: ()=>use(()=>decodeBase64url(module.beginHandshake(handle))),
+    finishHandshake: (message)=>use(()=>{
+        if (!module.finishHandshake(handle, encodeBase64url(message))) {
+          throw new Error("handshake_failed");
+        }
+      }),
+    encrypt: (aad, plaintext)=>use(()=>decodeBase64url(module.encrypt(handle, encodeBase64url(aad), encodeBase64url(plaintext)))),
+    decrypt: (aad, ciphertext)=>use(()=>decodeBase64url(module.decrypt(handle, encodeBase64url(aad), encodeBase64url(ciphertext)))),
+    close: ()=>{
+      if (closed) return;
+      closed = true;
+      try {
+        module.closeSession(handle);
+      } catch  {
+      // Close is idempotent and doesn't expose native provider diagnostics.
+      }
+    }
+  };
+  return Object.freeze(session);
+};
+const createResponder = (module, identityHandle, input)=>{
+  let handle;
+  try {
+    handle = module.createResponder(identityHandle, encodeBase64url(input.prologue), encodeBase64url(input.initiatorPublicKey));
+    if (!handlePattern.test(handle)) throw new Error("invalid_handle");
+  } catch  {
+    throw transportFailure();
+  }
+  let closed = false;
+  const use = (operation)=>{
+    if (closed) throw transportFailure();
+    try {
+      return operation();
+    } catch  {
+      closed = true;
+      try {
+        module.closeSession(handle);
+      } catch  {
+      // The application never receives provider-specific native cleanup details.
+      }
+      throw transportFailure();
+    }
+  };
+  const session = {
+    acceptHandshake: (message)=>use(()=>decodeBase64url(module.acceptHandshake(handle, encodeBase64url(message)))),
+    encrypt: (aad, plaintext)=>use(()=>decodeBase64url(module.encrypt(handle, encodeBase64url(aad), encodeBase64url(plaintext)))),
+    decrypt: (aad, ciphertext)=>use(()=>decodeBase64url(module.decrypt(handle, encodeBase64url(aad), encodeBase64url(ciphertext)))),
+    close: ()=>{
+      if (closed) return;
+      closed = true;
+      try {
+        module.closeSession(handle);
+      } catch  {
+      // Close is idempotent and doesn't expose native provider diagnostics.
+      }
+    }
+  };
+  return Object.freeze(session);
+};
+/** Adapts secure native identity handles to the shared relay identity port. */ export const createReactNativeIdentityProvider = (module)=>Object.freeze({
+    load: (projectId, peerId)=>{
+      try {
+        const identity = module.loadOrCreateIdentity(projectId, peerId);
+        if (!handlePattern.test(identity.identityHandle) || !keyPattern.test(identity.connectionPublicKey) || !keyPattern.test(identity.noiseStaticPublicKey)) throw new Error("invalid_native_identity");
+        const identityHandle = identity.identityHandle;
+        return Promise.resolve(Object.freeze({
+          publicIdentity: Object.freeze({
+            connectionPublicKey: Object.freeze({
+              kty: "OKP",
+              crv: "Ed25519",
+              x: identity.connectionPublicKey
+            }),
+            noiseStaticPublicKey: Object.freeze({
+              kty: "OKP",
+              crv: "X25519",
+              x: identity.noiseStaticPublicKey
+            })
+          }),
+          signConnectionProof: (input)=>{
+            try {
+              const proof = module.signConnectionProof(identityHandle, JSON.stringify(input));
+              if (proof.split(".").length !== 3) throw new Error("invalid_proof");
+              return Promise.resolve(proof);
+            } catch  {
+              return Promise.reject(new BridgePeerError("GRANT_FAILED"));
+            }
+          },
+          createInitiator: (input)=>createInitiator(module, identityHandle, input),
+          createResponder: (input)=>createResponder(module, identityHandle, input)
+        }));
+      } catch (error) {
+        if (error instanceof BridgePeerError) return Promise.reject(error);
+        return Promise.reject(new BridgePeerError("KEYSTORE_ERROR"));
+      }
+    }
+  });

package/src/react-native/lifecycle.d.ts

@@ -0,0 +1,8 @@
+import type { BridgePeerPlatformLifecycle } from "../core/mod.js";
+/** Minimal React Native AppState contract consumed by the platform adapter. */ export type ReactNativeAppState = Readonly<{
+  readonly currentState: string;
+  addEventListener(event: "change", listener: (state: string) => void): Readonly<{
+    remove(): void;
+  }>;
+}>;
+/** Maps React Native AppState into the core's active versus suspended lifecycle. */ export declare const createReactNativeLifecycle: (appState: ReactNativeAppState) => BridgePeerPlatformLifecycle;

package/src/react-native/lifecycle.js

@@ -0,0 +1,9 @@
+/** Maps React Native AppState into the core's active versus suspended lifecycle. */ export const createReactNativeLifecycle = (appState)=>Object.freeze({
+    get active () {
+      return appState.currentState === "active";
+    },
+    subscribe: (listener)=>{
+      const subscription = appState.addEventListener("change", (state)=>listener(state === "active"));
+      return ()=>subscription.remove();
+    }
+  });

package/src/react-native/mod.d.ts

@@ -0,0 +1,20 @@
+import { type BridgePeer, type BridgePeerCoreOptions, type BridgePeerPlatformLifecycle } from "../core/mod.js";
+import type { BridgeRelayIdentityProvider } from "../relay/identity.js";
+import type { BridgeWebSocketFactory } from "../relay/frame-channel.js";
+import { type ReactNativeAppState } from "./lifecycle.js";
+import { type GenationBridgeNativeModule } from "./native-module.js";
+/** Default managed relay endpoint used by the React Native happy path. */ export declare const defaultBridgeRelayUrl: "wss://relay.genation.com/v1/relay";
+/** React Native options layered on the shared public peer facade. */ export type BridgePeerOptions = BridgePeerCoreOptions & Readonly<{
+  relayUrl?: string;
+  nativeModule?: GenationBridgeNativeModule;
+  appState?: ReactNativeAppState;
+  identityProvider?: BridgeRelayIdentityProvider;
+  platformLifecycle?: BridgePeerPlatformLifecycle;
+  webSocketFactory?: BridgeWebSocketFactory;
+  operationTimeoutMs?: number;
+}>;
+/** Creates one foreground React Native peer through the conditional mobile adapter. */ export declare const createBridgePeer: (options: BridgePeerOptions) => BridgePeer;
+export * from "../core/mod.js";
+export { createReactNativeIdentityProvider, type GenationBridgeNativeModule } from "./identity-provider.js";
+export { createReactNativeLifecycle } from "./lifecycle.js";
+export { type ReactNativeAppState } from "./lifecycle.js";

package/src/react-native/mod.js

@@ -0,0 +1,36 @@
+import { BridgePeerError, createBridgePeerCore } from "../core/mod.js";
+import { createRelayRuntime } from "../relay/runtime.js";
+import { createReactNativeIdentityProvider } from "./identity-provider.js";
+import { createReactNativeLifecycle } from "./lifecycle.js";
+import { loadReactNative, resolveGenationBridgeNativeModule } from "./native-module.js";
+/** Default managed relay endpoint used by the React Native happy path. */ export const defaultBridgeRelayUrl = "wss://relay.genation.com/v1/relay";
+const validateRelayUrl = (value)=>{
+  try {
+    const url = new URL(value);
+    const loopback = url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "[::1]";
+    if (url.protocol !== "wss:" && !(url.protocol === "ws:" && loopback)) {
+      throw new Error("insecure_relay");
+    }
+  } catch  {
+    throw new BridgePeerError("INVALID_CONFIGURATION");
+  }
+};
+/** Creates one foreground React Native peer through the conditional mobile adapter. */ export const createBridgePeer = (options)=>{
+  const relayUrl = options.relayUrl ?? defaultBridgeRelayUrl;
+  validateRelayUrl(relayUrl);
+  const native = options.nativeModule ?? (options.identityProvider === undefined ? resolveGenationBridgeNativeModule() : undefined);
+  const identityProvider = options.identityProvider ?? createReactNativeIdentityProvider(native);
+  const lifecycle = options.platformLifecycle ?? createReactNativeLifecycle(options.appState ?? loadReactNative().AppState);
+  return createBridgePeerCore({
+    ...options,
+    lifecycle
+  }, createRelayRuntime({
+    relayUrl,
+    identityProvider,
+    webSocketFactory: options.webSocketFactory,
+    operationTimeoutMs: options.operationTimeoutMs
+  }));
+};
+export * from "../core/mod.js";
+export { createReactNativeIdentityProvider } from "./identity-provider.js";
+export { createReactNativeLifecycle } from "./lifecycle.js";

package/src/react-native/native-module.d.ts

@@ -0,0 +1,17 @@
+/** Public-only identity descriptor returned by native secure storage. */ export type NativePeerIdentity = Readonly<{
+  identityHandle: string;
+  connectionPublicKey: string;
+  noiseStaticPublicKey: string;
+}>;
+/** Synchronous native boundary required by the foreground mobile adapter. */ export type GenationBridgeNativeModule = {
+  loadOrCreateIdentity(projectId: string, peerId: string): NativePeerIdentity;
+  signConnectionProof(identityHandle: string, inputJson: string): string;
+  createInitiator(identityHandle: string, prologue: string, responderPublicKey: string): string;
+  createResponder(identityHandle: string, prologue: string, initiatorPublicKey: string): string;
+  beginHandshake(sessionHandle: string): string;
+  finishHandshake(sessionHandle: string, message: string): boolean;
+  acceptHandshake(sessionHandle: string, message: string): string;
+  encrypt(sessionHandle: string, aad: string, plaintext: string): string;
+  decrypt(sessionHandle: string, aad: string, ciphertext: string): string;
+  closeSession(sessionHandle: string): unknown;
+};

package/src/react-native/native-module.js

@@ -0,0 +1,9 @@
+import { BridgePeerError } from "../core/mod.js";
+/** Resolves the native host selected by the React Native conditional export. */ export const resolveGenationBridgeNativeModule = ()=>{
+  const installed = globalThis.__genationBridgePeerNative;
+  if (installed !== undefined) return installed;
+  const module = loadReactNative().NativeModules.GenationBridgePeer;
+  if (module === undefined) throw new BridgePeerError("KEYSTORE_ERROR");
+  return module;
+};
+/** Loads the conditional host dependency without probing process or user agent state. */ export const loadReactNative = ()=>require("react-native");

package/src/relay/encoding.js

@@ -0,0 +1,32 @@
+import { peerGrantClaimsSchema } from "@genation/bridge-contracts";
+import { BridgePeerError } from "../core/mod.js";
+/** Encodes bytes as canonical unpadded base64url. */ export const encodeBase64url = (value)=>{
+  const pieces = [];
+  const chunkSize = 0x8000;
+  for(let offset = 0; offset < value.length; offset += chunkSize){
+    pieces.push(String.fromCharCode(...value.subarray(offset, offset + chunkSize)));
+  }
+  return btoa(pieces.join("")).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+};
+/** Decodes canonical unpadded base64url or throws a sanitized transport error. */ export const decodeBase64url = (value)=>{
+  try {
+    const padding = "=".repeat((4 - value.length % 4) % 4);
+    const bytes = Uint8Array.from(atob(value.replaceAll("-", "+").replaceAll("_", "/") + padding), (character)=>character.charCodeAt(0));
+    if (encodeBase64url(bytes) !== value) throw new Error("noncanonical");
+    return bytes;
+  } catch  {
+    throw new BridgePeerError("TRANSPORT_ERROR");
+  }
+};
+/** Parses public grant claims without treating the peer as a signature authority. */ export const parseRelayGrantClaims = (grant)=>{
+  try {
+    const segments = grant.split(".");
+    if (segments.length !== 3) throw new Error("invalid_compact");
+    const payload = new TextDecoder("utf-8", {
+      fatal: true
+    }).decode(decodeBase64url(segments[1]));
+    return peerGrantClaimsSchema.parse(JSON.parse(payload));
+  } catch  {
+    throw new BridgePeerError("GRANT_FAILED");
+  }
+};

package/src/relay/frame-channel.d.ts

@@ -0,0 +1 @@
+/** WebSocket constructor boundary used by Node tests and platform composition. */ export type BridgeWebSocketFactory = (url: string) => WebSocket;