@appattest/react-native 0.1.0

package/lib/typescript/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @appattest/react-native — public API.
+ *
+ * Surface mirrors the Swift SDK's bridge translation:
+ *   - AppAttest.start() — fire-and-forget setup (zero-arg)
+ *   - AppAttest.getSecret(name) — Promise<string | null>
+ *   - AppAttest.getAllSecrets() — Promise<Record<string, string>>
+ *   - AppAttest.getState() — Promise<AppAttestState>
+ *   - AppAttest.waitForReady() — Promise<void>
+ *   - AppAttest.retry() — Promise<void>
+ *   - AppAttest.addStateListener(fn) — (state) => void; returns unsubscribe
+ *   - AppAttest.setDebugMode
+ *
+ * React hooks (idiomatic for RN consumers):
+ *   - useSecret(name) — string | null, re-renders on rotation
+ *   - useAllSecrets() — Record<string, string>, re-renders on rotation
+ *   - useAppAttestState() — AppAttestState, re-renders on transition
+ *
+ * There is no sandbox-mode modal logic. Developers handle their
+ * own UX for `.subscriptionRequired` / `.creditsRequired` / `.unavailable`.
+ */
+/**
+ * Lifecycle state. Mirrors `AppAttestClient.State` on the native side.
+ */
+export type AppAttestStateName = 'initializing' | 'attesting' | 'syncing' | 'ready' | 'subscription_required' | 'credits_required' | 'unavailable';
+export interface AppAttestState {
+    name: AppAttestStateName;
+    error?: AppAttestError;
+}
+/**
+ * Typed error thrown by every method. `code` matches the Swift SDK's
+ * `AppAttestError.code` one-for-one.
+ */
+export declare class AppAttestError extends Error {
+    readonly code: string;
+    /** For `subscription_required`: URL to (re)start the project subscription. */
+    readonly subscribeUrl?: string;
+    /** For `credits_required`: URL to top up the project balance. */
+    readonly topupUrl?: string;
+    readonly nativeError?: unknown;
+    constructor(code: string, message: string, extras?: {
+        subscribeUrl?: string;
+        topupUrl?: string;
+        nativeError?: unknown;
+    });
+    /**
+     * Single accessor for the dashboard URL regardless of code. Returns
+     * `subscribeUrl` for `subscription_required`, `topupUrl` for
+     * `credits_required`, else `undefined`.
+     */
+    get actionUrl(): string | undefined;
+}
+/** Stable string codes. Match Swift `AppAttestError.code` one-for-one. */
+export declare const ErrorCode: {
+    readonly SubscriptionRequired: "subscription_required";
+    readonly CreditsRequired: "credits_required";
+    readonly AttestationRejected: "attestation_rejected";
+    readonly ServiceUnavailable: "service_unavailable";
+    readonly Network: "network";
+    readonly DebugModeReleaseBlocked: "debug_mode_release_blocked";
+    readonly InvalidArgument: "invalid_argument";
+};
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+export type DebugMode = 'production' | 'local';
+export declare const AppAttest: {
+    /**
+     * Synchronous, idempotent setup. Zero-argument. Apple's AAGUID
+     * determines the bucket (sandbox vs production) server-side; the SDK
+     * is bucket-blind.
+     */
+    start(): Promise<void>;
+    /** Awaits a terminal state. Resolves on `ready`; rejects with
+     *  AppAttestError on subscriptionRequired / creditsRequired / unavailable. */
+    waitForReady(): Promise<void>;
+    /** Re-runs the background sync. */
+    retry(): Promise<void>;
+    /** Wipes stored credentials and secrets. */
+    reset(): Promise<void>;
+    /**
+     * Invalidate the cached secrets bundle and immediately sync. Keeps
+     * attestation credentials. Forces a 200 on the next sync, which
+     * consumes one credit on the production bucket.
+     *
+     * Use this for host-app "force refresh" / "sync now" UX. For wiping
+     * everything (including attestation), see ``reset()``.
+     */
+    invalidateBundle(): Promise<void>;
+    /** Returns the secret for `name`, or `null`. */
+    getSecret(name: string): Promise<string | null>;
+    /** Snapshot of every synced secret. */
+    getAllSecrets(): Promise<Record<string, string>>;
+    /** Current state snapshot. */
+    getState(): Promise<AppAttestState>;
+    /** Subscribe to state transitions. Returns an unsubscribe fn. */
+    addStateListener(listener: (state: AppAttestState) => void): () => void;
+    /** Set runtime mode. `'production'` (or `null`) is default. */
+    setDebugMode(mode: DebugMode | null, stubs?: Record<string, string>): Promise<void>;
+};
+/**
+ * React hook returning the current value of `secrets[name]`. Re-renders
+ * the host component whenever the underlying value changes (e.g. after
+ * a foreground rotation pulled new data).
+ */
+export declare function useSecret(name: string): string | null;
+/**
+ * React hook returning every synced secret. Re-renders on rotation.
+ */
+export declare function useAllSecrets(): Record<string, string>;
+/**
+ * React hook returning the current `AppAttestState`. Re-renders on
+ * every transition.
+ */
+export declare function useAppAttestState(): AppAttestState;
+export default AppAttest;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AASH;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC1B,cAAc,GACd,WAAW,GACX,SAAS,GACT,OAAO,GACP,uBAAuB,GACvB,kBAAkB,GAClB,aAAa,CAAC;AAElB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,kBAAkB,CAAC;IACzB,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;gBAG7B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE;QACP,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB;IAUH;;;;OAIG;IACH,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;CACF;AAED,0EAA0E;AAC1E,eAAO,MAAM,SAAS;;;;;;;;CAQZ,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEnE,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,OAAO,CAAC;AAwC/C,eAAO,MAAM,SAAS;IACpB;;;;OAIG;aACM,OAAO,CAAC,IAAI,CAAC;IAItB;kFAC8E;oBAC9D,OAAO,CAAC,IAAI,CAAC;IAI7B,mCAAmC;aAC1B,OAAO,CAAC,IAAI,CAAC;IAItB,4CAA4C;aACnC,OAAO,CAAC,IAAI,CAAC;IAItB;;;;;;;OAOG;wBACiB,OAAO,CAAC,IAAI,CAAC;IAIjC,gDAAgD;oBAChC,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAI/C,uCAAuC;qBACtB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAIhD,8BAA8B;gBACZ,OAAO,CAAC,cAAc,CAAC;IAKzC,iEAAiE;+BACtC,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI;IAOvE,+DAA+D;uBAC5C,SAAS,GAAG,IAAI,UAAU,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAMpF,CAAC;AAIF;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmBrD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAmBtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAclD;AAED,eAAe,SAAS,CAAC"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@appattest/react-native",
+  "version": "0.1.0",
+  "description": "React Native bridge for AppAttest — App-Attest-gated secret delivery for iOS.",
+  "main": "lib/commonjs/index.js",
+  "module": "lib/module/index.js",
+  "types": "lib/typescript/index.d.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "files": [
+    "src",
+    "lib",
+    "ios",
+    "!ios/build",
+    "*.podspec",
+    "!**/.*"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "prepare": "bob build"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "node",
+    "testMatch": [
+      "<rootDir>/__tests__/**/*.test.ts"
+    ]
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "app-attest",
+    "secrets",
+    "keychain"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AppAttest/appAttest-sdk.git",
+    "directory": "bridges/react-native"
+  },
+  "author": "Bault LLC",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/AppAttest/appAttest-sdk/issues"
+  },
+  "homepage": "https://github.com/AppAttest/appAttest-sdk/tree/main/bridges/react-native#readme",
+  "peerDependencies": {
+    "react": "*",
+    "react-native": ">=0.71.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/react": "^18.0.0",
+    "jest": "^29.7.0",
+    "react-native": "^0.77.0",
+    "react-native-builder-bob": "^0.42.1",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.4.0"
+  },
+  "codegenConfig": {
+    "name": "RNAppAttestSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {}
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      ["commonjs"],
+      ["module"],
+      ["typescript", { "project": "tsconfig.json" }]
+    ]
+  }
+}

package/src/NativeAppAttest.ts

@@ -0,0 +1,70 @@
+/**
+ * TurboModule spec for the AppAttest iOS native module.
+ *
+ * Codegen reads this file. The shape is restricted to what TurboModule
+ * codegen can serialize (primitives, Object, arrays of primitives,
+ * Promises, null).
+ *
+ * Errors: rejection objects carry `{ code, message,
+ * subscribeUrl?, topupUrl? }`. The TS wrapper in `index.ts` translates
+ * these into `AppAttestError`.
+ */
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  // Lifecycle
+
+  /** Synchronous, idempotent setup. Zero-argument (bucket is
+   *  AAGUID-derived server-side). */
+  start(): Promise<void>;
+
+  /** Awaits the next terminal state. Resolves on `ready`; rejects on
+   *  subscriptionRequired / creditsRequired / unavailable. */
+  waitForReady(): Promise<void>;
+
+  /** Re-runs the background sync. */
+  retry(): Promise<void>;
+
+  /** Wipes stored credentials and secrets. */
+  reset(): Promise<void>;
+
+  /** Invalidate the cached secrets bundle and immediately sync. Keeps
+   *  attestation; forces a 200 (1 credit on production). */
+  invalidateBundle(): Promise<void>;
+
+  // Reads
+
+  /** Synchronous-feeling secret lookup. Returns `null` if not yet
+   *  synced or absent. */
+  getSecret(name: string): Promise<string | null>;
+
+  /** Snapshot of every synced secret as `{ [name]: value }`. */
+  getAllSecrets(): Promise<{ [key: string]: string }>;
+
+  /** Current state as `{ name, error? }`. */
+  getState(): Promise<{
+    name: string;
+    error?: {
+      code: string;
+      message: string;
+      subscribeUrl?: string;
+      topupUrl?: string;
+    };
+  }>;
+
+  // Configuration
+
+  /** `null` / `'production'` for production; `'local'` for the DEBUG-only
+   *  stub mode. `'local'` requires `stubs`. */
+  setDebugMode(name: string | null, stubs: { [key: string]: string } | null): Promise<void>;
+
+  // setApiBaseUrl removed — base URL is hardcoded in the Swift SDK.
+
+  // Event emitter plumbing
+
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('RNAppAttest');

package/src/index.ts

@@ -0,0 +1,282 @@
+/**
+ * @appattest/react-native — public API.
+ *
+ * Surface mirrors the Swift SDK's bridge translation:
+ *   - AppAttest.start() — fire-and-forget setup (zero-arg)
+ *   - AppAttest.getSecret(name) — Promise<string | null>
+ *   - AppAttest.getAllSecrets() — Promise<Record<string, string>>
+ *   - AppAttest.getState() — Promise<AppAttestState>
+ *   - AppAttest.waitForReady() — Promise<void>
+ *   - AppAttest.retry() — Promise<void>
+ *   - AppAttest.addStateListener(fn) — (state) => void; returns unsubscribe
+ *   - AppAttest.setDebugMode
+ *
+ * React hooks (idiomatic for RN consumers):
+ *   - useSecret(name) — string | null, re-renders on rotation
+ *   - useAllSecrets() — Record<string, string>, re-renders on rotation
+ *   - useAppAttestState() — AppAttestState, re-renders on transition
+ *
+ * There is no sandbox-mode modal logic. Developers handle their
+ * own UX for `.subscriptionRequired` / `.creditsRequired` / `.unavailable`.
+ */
+
+import { useEffect, useState } from 'react';
+import { NativeEventEmitter, NativeModules } from 'react-native';
+import NativeAppAttest from './NativeAppAttest';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const eventEmitter = new NativeEventEmitter(NativeModules.RNAppAttest as any);
+
+/**
+ * Lifecycle state. Mirrors `AppAttestClient.State` on the native side.
+ */
+export type AppAttestStateName =
+  | 'initializing'
+  | 'attesting'
+  | 'syncing'
+  | 'ready'
+  | 'subscription_required'
+  | 'credits_required'
+  | 'unavailable';
+
+export interface AppAttestState {
+  name: AppAttestStateName;
+  error?: AppAttestError;
+}
+
+/**
+ * Typed error thrown by every method. `code` matches the Swift SDK's
+ * `AppAttestError.code` one-for-one.
+ */
+export class AppAttestError extends Error {
+  readonly code: string;
+  /** For `subscription_required`: URL to (re)start the project subscription. */
+  readonly subscribeUrl?: string;
+  /** For `credits_required`: URL to top up the project balance. */
+  readonly topupUrl?: string;
+  readonly nativeError?: unknown;
+
+  constructor(
+    code: string,
+    message: string,
+    extras?: {
+      subscribeUrl?: string;
+      topupUrl?: string;
+      nativeError?: unknown;
+    },
+  ) {
+    super(message);
+    this.name = 'AppAttestError';
+    this.code = code;
+    this.subscribeUrl = extras?.subscribeUrl;
+    this.topupUrl = extras?.topupUrl;
+    this.nativeError = extras?.nativeError;
+  }
+
+  /**
+   * Single accessor for the dashboard URL regardless of code. Returns
+   * `subscribeUrl` for `subscription_required`, `topupUrl` for
+   * `credits_required`, else `undefined`.
+   */
+  get actionUrl(): string | undefined {
+    return this.subscribeUrl ?? this.topupUrl;
+  }
+}
+
+/** Stable string codes. Match Swift `AppAttestError.code` one-for-one. */
+export const ErrorCode = {
+  SubscriptionRequired: 'subscription_required',
+  CreditsRequired: 'credits_required',
+  AttestationRejected: 'attestation_rejected',
+  ServiceUnavailable: 'service_unavailable',
+  Network: 'network',
+  DebugModeReleaseBlocked: 'debug_mode_release_blocked',
+  InvalidArgument: 'invalid_argument',
+} as const;
+
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+
+export type DebugMode = 'production' | 'local';
+
+interface ErrorEnvelope {
+  code?: string;
+  message?: string;
+  userInfo?: {
+    subscribeUrl?: string;
+    topupUrl?: string;
+  };
+  // RN flattens NSError userInfo onto the rejection too; cover both shapes.
+  subscribeUrl?: string;
+  topupUrl?: string;
+}
+
+function buildError(e: ErrorEnvelope, native: unknown): AppAttestError {
+  return new AppAttestError(e.code ?? 'internal_error', e.message ?? String(native), {
+    subscribeUrl: e.userInfo?.subscribeUrl ?? e.subscribeUrl,
+    topupUrl: e.userInfo?.topupUrl ?? e.topupUrl,
+    nativeError: native,
+  });
+}
+
+async function wrap<T>(p: Promise<T>): Promise<T> {
+  try {
+    return await p;
+  } catch (err) {
+    throw buildError(err as ErrorEnvelope, err);
+  }
+}
+
+interface NativeStateRaw {
+  name: string;
+  error?: ErrorEnvelope;
+}
+
+function decodeState(raw: NativeStateRaw): AppAttestState {
+  const error = raw.error ? buildError(raw.error, raw.error) : undefined;
+  return { name: raw.name as AppAttestStateName, error };
+}
+
+export const AppAttest = {
+  /**
+   * Synchronous, idempotent setup. Zero-argument. Apple's AAGUID
+   * determines the bucket (sandbox vs production) server-side; the SDK
+   * is bucket-blind.
+   */
+  start(): Promise<void> {
+    return wrap(NativeAppAttest.start());
+  },
+
+  /** Awaits a terminal state. Resolves on `ready`; rejects with
+   *  AppAttestError on subscriptionRequired / creditsRequired / unavailable. */
+  waitForReady(): Promise<void> {
+    return wrap(NativeAppAttest.waitForReady());
+  },
+
+  /** Re-runs the background sync. */
+  retry(): Promise<void> {
+    return wrap(NativeAppAttest.retry());
+  },
+
+  /** Wipes stored credentials and secrets. */
+  reset(): Promise<void> {
+    return wrap(NativeAppAttest.reset());
+  },
+
+  /**
+   * Invalidate the cached secrets bundle and immediately sync. Keeps
+   * attestation credentials. Forces a 200 on the next sync, which
+   * consumes one credit on the production bucket.
+   *
+   * Use this for host-app "force refresh" / "sync now" UX. For wiping
+   * everything (including attestation), see ``reset()``.
+   */
+  invalidateBundle(): Promise<void> {
+    return wrap(NativeAppAttest.invalidateBundle());
+  },
+
+  /** Returns the secret for `name`, or `null`. */
+  getSecret(name: string): Promise<string | null> {
+    return wrap(NativeAppAttest.getSecret(name));
+  },
+
+  /** Snapshot of every synced secret. */
+  getAllSecrets(): Promise<Record<string, string>> {
+    return wrap(NativeAppAttest.getAllSecrets());
+  },
+
+  /** Current state snapshot. */
+  async getState(): Promise<AppAttestState> {
+    const raw = await wrap(NativeAppAttest.getState());
+    return decodeState(raw as NativeStateRaw);
+  },
+
+  /** Subscribe to state transitions. Returns an unsubscribe fn. */
+  addStateListener(listener: (state: AppAttestState) => void): () => void {
+    const subscription = eventEmitter.addListener('stateChanged', (raw) => {
+      listener(decodeState(raw as NativeStateRaw));
+    });
+    return () => subscription.remove();
+  },
+
+  /** Set runtime mode. `'production'` (or `null`) is default. */
+  setDebugMode(mode: DebugMode | null, stubs?: Record<string, string>): Promise<void> {
+    return wrap(NativeAppAttest.setDebugMode(mode, stubs ?? null));
+  },
+
+  // setApiBaseUrl is not exposed — the base URL is hardcoded in the Swift
+  // SDK. There is no runtime override path from JavaScript.
+};
+
+// MARK: - React hooks
+
+/**
+ * React hook returning the current value of `secrets[name]`. Re-renders
+ * the host component whenever the underlying value changes (e.g. after
+ * a foreground rotation pulled new data).
+ */
+export function useSecret(name: string): string | null {
+  const [value, setValue] = useState<string | null>(null);
+  useEffect(() => {
+    let active = true;
+    AppAttest.getSecret(name).then((v) => { if (active) setValue(v); }).catch(() => {});
+    const unsubscribe = AppAttest.addStateListener(async (s) => {
+      if (s.name === 'ready') {
+        try {
+          const v = await AppAttest.getSecret(name);
+          if (active) setValue(v);
+        } catch { /* ignore */ }
+      }
+    });
+    return () => {
+      active = false;
+      unsubscribe();
+    };
+  }, [name]);
+  return value;
+}
+
+/**
+ * React hook returning every synced secret. Re-renders on rotation.
+ */
+export function useAllSecrets(): Record<string, string> {
+  const [all, setAll] = useState<Record<string, string>>({});
+  useEffect(() => {
+    let active = true;
+    AppAttest.getAllSecrets().then((v) => { if (active) setAll(v); }).catch(() => {});
+    const unsubscribe = AppAttest.addStateListener(async (s) => {
+      if (s.name === 'ready') {
+        try {
+          const v = await AppAttest.getAllSecrets();
+          if (active) setAll(v);
+        } catch { /* ignore */ }
+      }
+    });
+    return () => {
+      active = false;
+      unsubscribe();
+    };
+  }, []);
+  return all;
+}
+
+/**
+ * React hook returning the current `AppAttestState`. Re-renders on
+ * every transition.
+ */
+export function useAppAttestState(): AppAttestState {
+  const [state, setState] = useState<AppAttestState>({ name: 'initializing' });
+  useEffect(() => {
+    let active = true;
+    AppAttest.getState().then((s) => { if (active) setState(s); }).catch(() => {});
+    const unsubscribe = AppAttest.addStateListener((s) => {
+      if (active) setState(s);
+    });
+    return () => {
+      active = false;
+      unsubscribe();
+    };
+  }, []);
+  return state;
+}
+
+export default AppAttest;