@latchway/react-native 0.0.0-bootstrap.0 → 1.0.0

package/src/coordinator.ts

@@ -0,0 +1,195 @@
+import { LatchwayError } from "@latchway/client";
+import type { RuntimeComponentConfiguration, RuntimeConfiguration } from "./config.js";
+import { fromNativeError, nativeUnavailable } from "./errors.js";
+import { assertNoCredentialFields } from "./native-output.js";
+import { nativeModule, type NativeLatchwayModule } from "./native/bridge.js";
+import type { ReactNativePlatform } from "./types.js";
+import { CONTRACT_VERSION, PROTOCOL_VERSION, SDK_VERSION } from "./version.js";
+
+interface Compatibility {
+  platform: ReactNativePlatform;
+  nativeSDKVersion: string;
+  contractVersion: string;
+  protocolVersion: number;
+}
+
+interface Entry {
+  clientID: string;
+  fingerprint: string;
+  module: NativeLatchwayModule;
+  ready: Promise<Compatibility>;
+  references: number;
+}
+
+export interface NativeLease {
+  clientID: string;
+  module: NativeLatchwayModule;
+  ready: Promise<Compatibility>;
+  release(): Promise<void>;
+}
+
+const entries = new Map<string, Entry>();
+const componentEntries = new Map<string, Entry>();
+const moduleIDs = new WeakMap<object, number>();
+let nextModuleID = 1;
+let nextClientID = 1;
+
+export async function acquire(config: RuntimeConfiguration): Promise<NativeLease> {
+  let module: NativeLatchwayModule;
+  try {
+    module = await nativeModule();
+  } catch (cause) {
+    throw nativeUnavailable(cause);
+  }
+  const moduleID = identityFor(module);
+  const key = `${moduleID}|${config.scope}`;
+  const existing = entries.get(key);
+  if (existing !== undefined) {
+    if (existing.fingerprint !== config.fingerprint) {
+      throw new LatchwayError(
+        "client_configuration_invalid",
+        "Conflicting Latchway native configuration is active for this application scope.",
+      );
+    }
+    existing.references += 1;
+    return lease(entries, key, existing);
+  }
+
+  const clientID = `latchway-rn-${nextClientID++}`;
+  const entry: Entry = {
+    clientID,
+    fingerprint: config.fingerprint,
+    module,
+    references: 1,
+    ready: Promise.resolve({
+      platform: "react_native_ios",
+      nativeSDKVersion: "",
+      contractVersion: "",
+      protocolVersion: 0,
+    }),
+  };
+  entry.ready = module.configure(clientID, config.nativeJSON)
+    .then(parseCompatibility)
+    .catch(async (cause: unknown) => {
+      if (entries.get(key) === entry) entries.delete(key);
+      // configure may have created native state before compatibility parsing
+      // failed. Disposal is idempotent on both bridges and its failure must not
+      // hide the original configuration error.
+      try { await module.dispose(clientID); } catch { /* preserve the original failure */ }
+      throw fromNativeError(cause);
+    });
+  entries.set(key, entry);
+  return lease(entries, key, entry);
+}
+
+export async function acquireComponent(config: RuntimeComponentConfiguration): Promise<NativeLease> {
+  let module: NativeLatchwayModule;
+  try {
+    module = await nativeModule();
+  } catch (cause) {
+    throw nativeUnavailable(cause);
+  }
+  const moduleID = identityFor(module);
+  const key = `${moduleID}|component|${config.scope}`;
+  const existing = componentEntries.get(key);
+  if (existing !== undefined) {
+    if (existing.fingerprint !== config.fingerprint) {
+      throw new LatchwayError(
+        "client_configuration_invalid",
+        "Conflicting Latchway component configuration is active for this extension scope.",
+      );
+    }
+    existing.references += 1;
+    return lease(componentEntries, key, existing);
+  }
+
+  const clientID = `latchway-rn-component-${nextClientID++}`;
+  const entry: Entry = {
+    clientID,
+    fingerprint: config.fingerprint,
+    module,
+    references: 1,
+    ready: emptyCompatibility(),
+  };
+  entry.ready = module.configureComponent(clientID, config.nativeJSON, config.componentJSON)
+    .then(parseCompatibility)
+    .catch(async (cause: unknown) => {
+      if (componentEntries.get(key) === entry) componentEntries.delete(key);
+      try { await module.dispose(clientID); } catch { /* preserve the original failure */ }
+      throw fromNativeError(cause);
+    });
+  componentEntries.set(key, entry);
+  return lease(componentEntries, key, entry);
+}
+
+function lease(owner: Map<string, Entry>, key: string, entry: Entry): NativeLease {
+  let released = false;
+  return {
+    clientID: entry.clientID,
+    module: entry.module,
+    ready: entry.ready,
+    async release(): Promise<void> {
+      if (released) return;
+      released = true;
+      entry.references -= 1;
+      if (entry.references !== 0 || owner.get(key) !== entry) return;
+      owner.delete(key);
+      try {
+        await entry.ready;
+        await entry.module.dispose(entry.clientID);
+      } catch (cause) {
+        throw fromNativeError(cause);
+      }
+    },
+  };
+}
+
+function emptyCompatibility(): Promise<Compatibility> {
+  return Promise.resolve({
+    platform: "react_native_ios",
+    nativeSDKVersion: "",
+    contractVersion: "",
+    protocolVersion: 0,
+  });
+}
+
+function parseCompatibility(encoded: string): Compatibility {
+  const value = parseRecord(encoded, "native compatibility");
+  assertNoCredentialFields(value);
+  if (!hasOnlyKeys(value, ["platform", "nativeSDKVersion", "contractVersion", "protocolVersion"]) ||
+      (value.platform !== "react_native_ios" && value.platform !== "react_native_android") ||
+      typeof value.nativeSDKVersion !== "string" || value.nativeSDKVersion.length === 0 ||
+      value.nativeSDKVersion.length > 128 || /\p{Cc}/u.test(value.nativeSDKVersion) ||
+      value.contractVersion !== CONTRACT_VERSION || value.protocolVersion !== PROTOCOL_VERSION) {
+    throw new LatchwayError(
+      "protocol_response_invalid",
+      `The native Latchway SDK is incompatible with JavaScript SDK ${SDK_VERSION}.`,
+    );
+  }
+  return value as unknown as Compatibility;
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, names: readonly string[]): boolean {
+  const expected = new Set(names);
+  return Object.keys(value).every((name) => expected.has(name));
+}
+
+function parseRecord(encoded: string, label: string): Record<string, unknown> {
+  try {
+    const value: unknown = JSON.parse(encoded);
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      return value as Record<string, unknown>;
+    }
+  } catch {
+    // Report only a stable protocol error; native output may contain sensitive detail.
+  }
+  throw new LatchwayError("protocol_response_invalid", `Latchway returned invalid ${label}.`);
+}
+
+function identityFor(module: object): number {
+  const existing = moduleIDs.get(module);
+  if (existing !== undefined) return existing;
+  const value = nextModuleID++;
+  moduleIDs.set(module, value);
+  return value;
+}

package/src/errors.ts

@@ -0,0 +1,225 @@
+import { LatchwayError } from "@latchway/client";
+import type { LatchwayErrorCode } from "@latchway/client";
+import { isCanonicalRequestID } from "./request-id.js";
+import { assertNoCredentialFields } from "./native-output.js";
+
+const knownCodeMap = {
+  request_invalid: true,
+  identity_token_missing: true,
+  identity_token_invalid: true,
+  identity_token_expired: true,
+  identity_reauthentication_required: true,
+  attestation_required: true,
+  attestation_unsupported: true,
+  attestation_invalid: true,
+  attestation_stale: true,
+  attestation_step_up_required: true,
+  dpop_missing: true,
+  dpop_invalid: true,
+  dpop_replayed: true,
+  dpop_nonce_required: true,
+  session_expired: true,
+  session_revoked: true,
+  refresh_token_reused: true,
+  installation_revoked: true,
+  installation_family_revoked: true,
+  installation_family_not_found: true,
+  component_definition_not_found: true,
+  component_not_configured: true,
+  component_not_provisioned: true,
+  component_revoked: true,
+  component_key_invalid: true,
+  component_key_replaced: true,
+  component_delegation_expired: true,
+  component_feature_not_granted: true,
+  component_parent_trust_expired: true,
+  component_direct_attestation_required: true,
+  containing_app_setup_required: true,
+  framework_integration_unsupported: true,
+  framework_version_unsupported: true,
+  transport_destination_not_allowed: true,
+  transport_request_not_replayable: true,
+  feature_not_found: true,
+  feature_not_allowed: true,
+  model_not_allowed: true,
+  quota_exceeded: true,
+  concurrency_exceeded: true,
+  output_limit_exceeded: true,
+  pricing_unavailable: true,
+  route_not_found: true,
+  upstream_unavailable: true,
+  upstream_timeout: true,
+  upstream_protocol_error: true,
+  configuration_invalid: true,
+  server_not_ready: true,
+  protocol_version_unsupported: true,
+  authentication_required: true,
+  permission_denied: true,
+  resource_not_found: true,
+  conflict: true,
+  etag_required: true,
+  etag_mismatch: true,
+  bootstrap_disabled: true,
+  rate_limited: true,
+  operation_indeterminate: true,
+  internal_error: true,
+  client_configuration_invalid: true,
+  storage_unavailable: true,
+  crypto_unavailable: true,
+  attestation_provider_missing: true,
+  protocol_response_invalid: true,
+  request_not_replayable: true,
+  network_error: true,
+} as const satisfies Record<LatchwayErrorCode, true>;
+
+const knownCodes: ReadonlySet<string> = new Set(Object.keys(knownCodeMap));
+
+const localCodeMap: Readonly<Record<string, LatchwayErrorCode>> = {
+  cancelled: "network_error",
+  invalid_configuration: "client_configuration_invalid",
+  invalid_request: "request_invalid",
+  key_unavailable: "crypto_unavailable",
+  secure_enclave_unavailable: "crypto_unavailable",
+  secure_state_unavailable: "storage_unavailable",
+  key_storage_failure: "storage_unavailable",
+  response_invalid: "protocol_response_invalid",
+  invalid_server_response: "protocol_response_invalid",
+  network_unavailable: "network_error",
+  transport_failure: "network_error",
+  session_unavailable: "session_expired",
+  attestation_unavailable: "attestation_unsupported",
+};
+
+export function fromNativeError(value: unknown): Error {
+  try {
+    assertNoCredentialFields(value);
+  } catch (cause) {
+    return cause instanceof LatchwayError
+      ? cause
+      : new LatchwayError("protocol_response_invalid", "Latchway returned unsafe native error metadata.");
+  }
+  if (isAbortError(value)) return abortError();
+  const record = isRecord(value) ? value : {};
+  const userInfo = isRecord(record.userInfo) ? record.userInfo : {};
+  const rawCode = firstString(record.code, userInfo.code);
+  const mapped = rawCode === undefined
+    ? "internal_error"
+    : localCodeMap[rawCode] ?? (knownCodes.has(rawCode)
+      ? rawCode as LatchwayErrorCode
+      : "internal_error");
+  const codeValues = presentValues(record, userInfo, ["code"]);
+  const requestIDValues = presentValues(record, userInfo, ["requestID", "request_id"]);
+  const requestIDCandidate = firstString(record.requestID, record.request_id, userInfo.requestID, userInfo.request_id);
+  const requestID = isCanonicalRequestID(requestIDCandidate) ? requestIDCandidate : undefined;
+  const statusValues = presentValues(record, userInfo, ["status"]);
+  const status = safeStatus(record.status ?? userInfo.status);
+  const retryableValues = presentValues(record, userInfo, ["retryable"]);
+  const retryable = record.retryable === true || userInfo.retryable === true;
+  const documentationURLValues = presentValues(
+    record,
+    userInfo,
+    ["documentationURL", "documentation_url"],
+  );
+  const canonicalNativeDocumentationURL = rawCode !== undefined && isNativeErrorCode(rawCode)
+    ? `https://docs.latchway.dev/errors/${rawCode.replaceAll("_", "-")}`
+    : undefined;
+  const documentationURLIsValid = documentationURLValues.length > 0 &&
+    canonicalNativeDocumentationURL !== undefined &&
+    documentationURLValues.every((candidate) => candidate === canonicalNativeDocumentationURL);
+  const operationValues = presentValues(record, userInfo, ["operationID", "operation_id"]);
+  const operationID = operationValues.length > 0 &&
+    operationValues.every((candidate) => candidate === operationValues[0]) &&
+    isCanonicalOperationID(operationValues[0])
+    ? operationValues[0]
+    : undefined;
+  const validIndeterminateMetadata = operationID !== undefined && requestID !== undefined &&
+    status === 503 && retryable && codeValues.length > 0 &&
+    codeValues.every((candidate) => candidate === "operation_indeterminate") &&
+    requestIDValues.length > 0 && requestIDValues.every((candidate) => candidate === requestID) &&
+    statusValues.length > 0 && statusValues.every((candidate) => candidate === 503) &&
+    retryableValues.length > 0 && retryableValues.every((candidate) => candidate === true);
+  const hasServerMetadata = requestIDValues.length > 0 || statusValues.length > 0;
+  if ((documentationURLValues.length > 0 && !documentationURLIsValid) ||
+      (hasServerMetadata && !documentationURLIsValid) ||
+      (mapped === "operation_indeterminate" && !validIndeterminateMetadata) ||
+      (mapped !== "operation_indeterminate" && operationValues.length > 0)) {
+    return new LatchwayError(
+      "protocol_response_invalid",
+      "Latchway returned invalid native error metadata.",
+      { requestID, status },
+    );
+  }
+  return new LatchwayError(mapped, safeMessage(firstString(record.message, userInfo.message)), {
+    requestID,
+    status,
+    retryable,
+    operationID,
+  });
+}
+
+export function nativeUnavailable(cause: unknown): LatchwayError {
+  return new LatchwayError(
+    "client_configuration_invalid",
+    "The Latchway native module is unavailable. Rebuild the application after installing the SDK.",
+    { cause },
+  );
+}
+
+export function abortError(): Error {
+  if (typeof DOMException === "function") return new DOMException("The operation was aborted.", "AbortError");
+  const error = new Error("The operation was aborted.");
+  error.name = "AbortError";
+  return error;
+}
+
+function isAbortError(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const code = firstString(value.code, value.name);
+  return code === "cancelled" || code === "E_ABORTED" || code === "AbortError";
+}
+
+function safeMessage(value: string | undefined): string {
+  if (value === undefined || value.length === 0) return "The Latchway native operation failed.";
+  const bounded = value.replace(/\p{Cc}/gu, " ").slice(0, 512);
+  if (/eyJ|lwa_|lws_|refresh.?token|identity.?token|integrity.?token|[A-Za-z0-9_-]{64,}/iu.test(bounded)) {
+    return "Sensitive native error detail was redacted.";
+  }
+  return bounded;
+}
+
+function safeStatus(value: unknown): number | undefined {
+  return Number.isInteger(value) && (value as number) >= 100 && (value as number) <= 599
+    ? value as number
+    : undefined;
+}
+
+function firstString(...values: unknown[]): string | undefined {
+  return values.find((value): value is string => typeof value === "string");
+}
+
+function presentValues(
+  record: Record<string, unknown>,
+  userInfo: Record<string, unknown>,
+  keys: readonly string[],
+): unknown[] {
+  const values: unknown[] = [];
+  for (const source of [record, userInfo]) {
+    for (const key of keys) {
+      const candidate = source[key];
+      if (Object.hasOwn(source, key) && candidate !== undefined && candidate !== null) values.push(candidate);
+    }
+  }
+  return values;
+}
+
+function isCanonicalOperationID(value: unknown): value is string {
+  return typeof value === "string" && /^arq_[0-7][0-9A-HJKMNPQRSTVWXYZ]{25}$/u.test(value);
+}
+
+function isNativeErrorCode(value: string): boolean {
+  return /^[a-z][a-z0-9_]{0,62}$/u.test(value);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+import { DefaultLatchwayClient } from "./client.js";
+import { DefaultLatchwayComponentClient } from "./component-client.js";
+import { configure, configureComponent } from "./config.js";
+import type {
+  LatchwayClient,
+  LatchwayComponentClient,
+  LatchwayComponentOptions,
+  LatchwayOptions,
+} from "./types.js";
+
+export { errorFromResponse, LatchwayError } from "@latchway/client";
+export {
+  CONTRACT_VERSION,
+  PROTOCOL_VERSION,
+  SDK_KIND,
+  SDK_VERSION,
+  SUPPORTED_PROTOCOL_VERSIONS,
+} from "./version.js";
+export type {
+  AndroidKeyPolicy,
+  AndroidSecurityOptions,
+  AppleSecurityOptions,
+  AppleSoftwareKeyFallbackPolicy,
+  FetchImplementation,
+  GetIdentityToken,
+  IdentityTokenProvider,
+  LatchwayClient,
+  LatchwayComponentClient,
+  LatchwayComponentOptions,
+  LatchwayFetchInit,
+  LatchwayFetch,
+  LatchwayOptions,
+  QuotaLimit,
+  QuotaSnapshot,
+  ReactNativeComponentDiagnostics,
+  ReactNativeComponentAppleOptions,
+  ReactNativeComponentTrustSource,
+  ReactNativeDiagnostics,
+  ReactNativeIOSComponent,
+  ReactNativeIOSComponentKind,
+  ReactNativeDirectAttestationComponent,
+  ReactNativeDirectAttestationComponentKind,
+  ReactNativePlatform,
+} from "./types.js";
+
+export function createLatchwayClient(options: LatchwayOptions): LatchwayClient {
+  return new DefaultLatchwayClient(configure(options));
+}
+
+/** Creates a client only for JavaScript executing inside the signed iOS extension bundle. */
+export function createLatchwayComponentClient(options: LatchwayComponentOptions): LatchwayComponentClient {
+  return new DefaultLatchwayComponentClient(configureComponent(options));
+}

package/src/native/NativeLatchway.ts

@@ -0,0 +1,75 @@
+import type { TurboModule } from "react-native";
+import { TurboModuleRegistry } from "react-native";
+
+export interface Spec extends TurboModule {
+  configure(clientID: string, configurationJSON: string): Promise<string>;
+  configureComponent(
+    clientID: string,
+    configurationJSON: string,
+    componentJSON: string,
+  ): Promise<string>;
+  startRequest(
+    clientID: string,
+    operationID: string,
+    identityToken: string,
+    requestJSON: string,
+  ): Promise<string>;
+  readResponseChunk(
+    clientID: string,
+    operationID: string,
+    responseID: string,
+    maximumBytes: number,
+  ): Promise<string>;
+  closeResponse(clientID: string, responseID: string): Promise<void>;
+  refresh(clientID: string, operationID: string, identityToken: string): Promise<void>;
+  quota(
+    clientID: string,
+    operationID: string,
+    identityToken: string,
+    feature: string,
+  ): Promise<string>;
+  diagnostics(clientID: string, operationID: string, identityToken: string): Promise<string>;
+  establishDirectAttestation(
+    clientID: string,
+    operationID: string,
+  ): Promise<void>;
+  componentDiagnostics(
+    clientID: string,
+    operationID: string,
+  ): Promise<string>;
+  prepareComponents(
+    clientID: string,
+    operationID: string,
+    identityToken: string,
+    componentsJSON: string,
+  ): Promise<string>;
+  replaceComponent(
+    clientID: string,
+    operationID: string,
+    identityToken: string,
+    componentJSON: string,
+  ): Promise<string>;
+  rootComponentDiagnostics(
+    clientID: string,
+    operationID: string,
+    componentJSON: string,
+  ): Promise<string>;
+  revokeComponent(
+    clientID: string,
+    operationID: string,
+    identityToken: string,
+    componentJSON: string,
+  ): Promise<void>;
+  revoke(clientID: string, operationID: string, identityToken: string): Promise<void>;
+  revokeFamily(clientID: string, operationID: string, identityToken: string): Promise<void>;
+  revokeFamilyWithComponents(
+    clientID: string,
+    operationID: string,
+    identityToken: string,
+    componentsJSON: string,
+  ): Promise<void>;
+  cancel(clientID: string, operationID: string): void;
+  dispose(clientID: string): Promise<void>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>("NativeLatchway");

package/src/native/bridge.ts

@@ -0,0 +1,23 @@
+import type { Spec } from "./NativeLatchway.js";
+
+export type NativeLatchwayModule = Spec;
+
+let testingModule: NativeLatchwayModule | undefined;
+
+export async function nativeModule(): Promise<NativeLatchwayModule> {
+  if (testingModule !== undefined) return testingModule;
+  try {
+    return (await import("./NativeLatchway.js")).default;
+  } catch (cause) {
+    const error = new Error(
+      "The Latchway TurboModule is unavailable. Rebuild the native application after installing @latchway/react-native.",
+      { cause },
+    );
+    error.name = "LatchwayNativeModuleUnavailable";
+    throw error;
+  }
+}
+
+export function setTestingNativeModule(module: NativeLatchwayModule | undefined): void {
+  testingModule = module;
+}

package/src/native-output.ts

@@ -0,0 +1,43 @@
+import { LatchwayError } from "@latchway/client";
+
+const forbiddenCredentialKeyFragments = [
+  "authorization",
+  "dpop",
+  "accesstoken",
+  "refreshtoken",
+  "privatekey",
+  "sessiontoken",
+  "identitytoken",
+  "integritytoken",
+  "attestationevidence",
+  "clientdatahash",
+  "requesthash",
+  "credential",
+  "secret",
+  "jwk",
+] as const;
+
+const forbiddenExactCredentialKeys = new Set(["key", "proof", "token"]);
+
+/** Fails closed when a native return or rejection envelope names credential material. */
+export function assertNoCredentialFields(value: unknown): void {
+  if (containsCredentialField(value)) {
+    throw new LatchwayError("protocol_response_invalid", "Latchway native output crossed the credential boundary.");
+  }
+}
+
+function containsCredentialField(value: unknown): boolean {
+  if (Array.isArray(value)) return value.some(containsCredentialField);
+  if (!isRecord(value)) return false;
+  for (const [key, item] of Object.entries(value)) {
+    const compact = key.replace(/[^A-Za-z0-9]/gu, "").toLowerCase();
+    if (forbiddenExactCredentialKeys.has(compact) ||
+        forbiddenCredentialKeyFragments.some((fragment) => compact.includes(fragment))) return true;
+    if (containsCredentialField(item)) return true;
+  }
+  return false;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/request-id.ts

@@ -0,0 +1,5 @@
+const requestIDPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u;
+
+export function isCanonicalRequestID(value: unknown): value is string {
+  return typeof value === "string" && value.length >= 8 && value.length <= 128 && requestIDPattern.test(value);
+}

package/src/testing.ts

@@ -0,0 +1,11 @@
+import { createLatchwayClient } from "./index.js";
+import { setTestingNativeModule, type NativeLatchwayModule } from "./native/bridge.js";
+
+/** Installs an in-process bridge for Node conformance tests. Never use this in an application build. */
+export function installNativeModuleForTesting(module: NativeLatchwayModule): () => void {
+  setTestingNativeModule(module);
+  return () => { setTestingNativeModule(undefined); };
+}
+
+export { createLatchwayClient };
+export type { NativeLatchwayModule };