react-native-intune 0.1.0-alpha.1

package/src/api/auth.ts

@@ -0,0 +1,73 @@
+/**
+ * Sign-in, for `authMode: 'builtin'` — the module owns MSAL (SPEC §3).
+ *
+ * Two tokens exist and only one of them appears here: the MAM service token is acquired
+ * internally and never crosses the bridge. Everything returned by these calls is for
+ * *your* API's scopes (SPEC §3.5).
+ */
+
+import NativeIntune from '../NativeIntune';
+import { assertAccountId } from '../internal/errors';
+import { toAuthAccount, toAuthResult } from '../internal/decode';
+import { enroll } from './enrollment';
+import type {
+  AcquireTokenParams,
+  AuthAccount,
+  AuthResult,
+  EnrollmentResult,
+  SignInParams,
+  SignOutParams,
+} from '../types';
+
+/**
+ * Uses the broker when one is present, which also gives device-wide SSO: a user already
+ * signed into Outlook usually gets a token with no prompt at all.
+ */
+export async function signIn(params: SignInParams = {}): Promise<AuthResult> {
+  return toAuthResult(await NativeIntune.signIn(params));
+}
+
+/**
+ * Cache-first. Rejects with `E_INTERACTION_REQUIRED` when a prompt is needed — the normal
+ * pattern is `signInSilent` first, `signIn` on that rejection.
+ */
+export async function signInSilent(
+  params: SignInParams = {}
+): Promise<AuthResult> {
+  return toAuthResult(await NativeIntune.signInSilent(params));
+}
+
+/** For your own API's scopes, after sign-in. */
+export async function acquireToken(
+  params: AcquireTokenParams
+): Promise<AuthResult> {
+  return toAuthResult(await NativeIntune.acquireToken(params));
+}
+
+/**
+ * Accounts with cached refresh tokens. Under single identity (SPEC §9) this holds at
+ * most one; more than one means state a reset should have cleared.
+ */
+export async function getAccounts(): Promise<AuthAccount[]> {
+  const accounts = await NativeIntune.getAccounts();
+  return accounts.map(toAuthAccount);
+}
+
+/**
+ * Removes the account from the MSAL cache. With `wipeIntune: true` it also runs the full
+ * reset sequence, which is what you want on logout — and which means **the process may
+ * terminate during this call on Android.**
+ */
+export function signOut(params: SignOutParams): Promise<void> {
+  assertAccountId(params.accountId);
+  return NativeIntune.signOut(params);
+}
+
+/** The common path in one call. Use the primitives when you need a step in between. */
+export async function signInAndEnroll(
+  params: SignInParams = {}
+): Promise<{ auth: AuthResult; enrollment: EnrollmentResult }> {
+  const auth = await signIn(params);
+  const enrollment = await enroll({ accountId: auth.accountId });
+  return { auth, enrollment };
+}

package/src/api/enrollment.ts

@@ -0,0 +1,112 @@
+/**
+ * Enrollment, state, and the reset sequence.
+ *
+ * The theme running through all three: **the SDK reports asynchronously and the process
+ * may not survive**. Nothing here resolves from a call returning, and nothing assumes
+ * the next line will run.
+ */
+
+import NativeIntune from '../NativeIntune';
+import { assertAccountId } from '../internal/errors';
+import { toEnrollmentResult, toIntuneState } from '../internal/decode';
+import type {
+  EnrollInteractiveParams,
+  EnrollmentResult,
+  EnrollParams,
+  IntuneState,
+  ResetHandler,
+  ResetParams,
+} from '../types';
+
+let resetHandler: ResetHandler | null = null;
+
+/**
+ * Clears the app's own local data during a reset. The module cannot do this for you — it
+ * does not know what you store or where.
+ *
+ * Registered rather than passed to `reset` because a reset can be *resumed* at launch
+ * from the journal, with no `reset` call in flight (SPEC §7).
+ */
+export function setResetHandler(handler: ResetHandler | null): void {
+  resetHandler = handler;
+}
+
+/**
+ * Resolves with a result for every outcome including failures — a non-success status is
+ * data, not an exception. It only rejects for programming errors.
+ *
+ * Expect seconds, and a spinner: the promise settles when the SDK reports through its
+ * delegate or notification, not when the underlying call returns.
+ *
+ * Read SPEC §8 before branching on `status`. `NotLicensed` and `NotTargeted` must not
+ * block the user; `Failed` must.
+ */
+export async function enroll(params: EnrollParams): Promise<EnrollmentResult> {
+  assertAccountId(params.accountId);
+  return toEnrollmentResult(
+    // '' rather than undefined: the Codegen spec has no optionals, so "not known" has to
+    // be a value the native side can recognise.
+    await NativeIntune.enroll({
+      accountId: params.accountId,
+      upn: params.upn ?? '',
+    })
+  );
+}
+
+/**
+ * **iOS only.** Hands the whole sign-in to the SDK: it shows its own credential screen,
+ * signs the user in, and enrolls them. No MSAL on our side, which is why this works
+ * before the built-in auth layer exists.
+ *
+ * Rejects with `E_SDK_UNAVAILABLE` on Android — `registerAccountForMAM` there always
+ * needs a token supplied by the app, so there is nothing equivalent to call.
+ *
+ * Like `enroll`, it resolves with a result for every outcome including failures.
+ */
+export async function enrollInteractive(
+  params: EnrollInteractiveParams = {}
+): Promise<EnrollmentResult> {
+  return toEnrollmentResult(
+    await NativeIntune.enrollInteractive({ upn: params.upn ?? '' })
+  );
+}
+
+/**
+ * The reconciliation primitive, and the intended way to drive this module. Call it at
+ * launch, compare against what your backend says the state should be, act on the
+ * difference. It never rejects.
+ */
+export async function getState(): Promise<IntuneState> {
+  return toIntuneState(await NativeIntune.getState());
+}
+
+/**
+ * Unregisters, unenrolls, optionally wipes corporate data, and clears the runtime
+ * configuration.
+ *
+ * **The process is expected to terminate during this call on Android** (SPEC §7). Do not
+ * write code after `await reset(...)` that must run — put the continuation in the
+ * launch-time reconciliation and let the journal resume it.
+ */
+export async function reset(params: ResetParams): Promise<void> {
+  // The order below is SPEC §7's, and it is not the intuitive one. The unregister has to
+  // happen before anything purges the account's tokens, and on Android the process is
+  // expected to die during it — so local cleanup cannot come first, and cannot be
+  // assumed to run at all. The journal carries the sequence across that death: if the
+  // native call never returns, the next launch sees `pendingReset` and calls reset()
+  // again with reason 'resume', landing back here.
+  const state = await getState().catch(() => null);
+  const accountId = state?.enrolledAccountId ?? null;
+
+  await NativeIntune.reset(params);
+
+  // Reached only if the process survived.
+  const handler = resetHandler;
+  if (handler !== null) {
+    // Deliberately not caught: if the app cannot clear its own data, the journal stays
+    // open and the reset is retried next launch rather than being marked done.
+    await handler({ reason: params.reason, accountId });
+  }
+
+  await NativeIntune.completeReset();
+}

package/src/api/events.ts

@@ -0,0 +1,87 @@
+/**
+ * Typed subscriptions.
+ *
+ * Every one of these can fire without the app having called anything: the SDK enrolls on
+ * its own retry schedule, an administrator can change policy, and a wipe is
+ * service-initiated. Subscribe at startup, not when you happen to be waiting (SPEC §4.4).
+ */
+
+import type { EmitterSubscription } from 'react-native';
+
+import { emitter } from '../internal/emitter';
+import {
+  nullableStr,
+  toBrokerStatus,
+  toEnrollmentResult,
+  toPolicySnapshot,
+  toRestartReason,
+} from '../internal/decode';
+import type {
+  BrokerStatus,
+  EnrollmentResult,
+  IntuneEvents,
+  PolicySnapshot,
+  RestartRequest,
+} from '../types';
+
+function subscribe<K extends keyof IntuneEvents>(
+  event: K,
+  decode: (raw: object) => IntuneEvents[K],
+  listener: (payload: IntuneEvents[K]) => void
+): EmitterSubscription {
+  return emitter.addListener(event, (raw: object) => listener(decode(raw)));
+}
+
+/** Also fires for the SDK's own background enrollment retries, which have no caller. */
+export function onEnrollmentResult(
+  listener: (result: EnrollmentResult) => void
+): EmitterSubscription {
+  return subscribe('enrollmentResult', toEnrollmentResult, listener);
+}
+
+/** The terminal state of a reset. */
+export function onUnenrollmentResult(
+  listener: (result: EnrollmentResult) => void
+): EmitterSubscription {
+  return subscribe('unenrollmentResult', toEnrollmentResult, listener);
+}
+
+/** An administrator changed policy — re-read whatever UI you gate on it. */
+export function onPolicyChanged(
+  listener: (policy: PolicySnapshot) => void
+): EmitterSubscription {
+  return subscribe('policyChanged', toPolicySnapshot, listener);
+}
+
+/** The user installed or removed Company Portal. */
+export function onBrokerStatusChanged(
+  listener: (status: BrokerStatus) => void
+): EmitterSubscription {
+  return subscribe('brokerStatusChanged', toBrokerStatus, listener);
+}
+
+/** **Service-initiated.** Can arrive with no prior app call at all. */
+export function onWipeRequested(
+  listener: (request: { accountId: string | null }) => void
+): EmitterSubscription {
+  return subscribe(
+    'wipeRequested',
+    (raw) => ({
+      accountId: nullableStr((raw as Record<string, unknown>).accountId),
+    }),
+    listener
+  );
+}
+
+/** iOS, on first policy application. See `configure({ restartHandledByApp })`. */
+export function onRestartRequired(
+  listener: (request: RestartRequest) => void
+): EmitterSubscription {
+  return subscribe(
+    'restartRequired',
+    (raw) => ({
+      reason: toRestartReason((raw as Record<string, unknown>).reason),
+    }),
+    listener
+  );
+}

package/src/api/lifecycle.ts

@@ -0,0 +1,75 @@
+/**
+ * Setup, and the two questions worth asking before it: is the SDK usable at all, and is
+ * a broker present.
+ */
+
+import NativeIntune from '../NativeIntune';
+import { toBrokerStatus } from '../internal/decode';
+import {
+  FileProtectionLevel,
+  type BrokerStatus,
+  type IntuneConfig,
+} from '../types';
+
+/**
+ * Configures the SDK for one customer tenant. Every other method rejects with
+ * `E_NOT_CONFIGURED` until this resolves.
+ *
+ * Two things it will refuse rather than paper over:
+ *
+ *   - a different `tenantId` than the active one — `E_RESET_REQUIRED`, because silently
+ *     reconfiguring would leave the old tenant enrolled, and the iOS runtime overrides
+ *     persist across restarts so the mismatch would survive a relaunch;
+ *   - an `Info.plist` that disagrees with it — `E_PLIST_CONFLICT`, see SPEC §5.1.2.
+ */
+export function configure(config: IntuneConfig): Promise<void> {
+  // Every optional becomes a concrete value here, so the native side never has to guess
+  // a default and the two platforms cannot drift apart on what the default was.
+  return NativeIntune.configure({
+    clientId: config.clientId,
+    tenantId: config.tenantId,
+    authority: config.authority,
+    redirectUri: config.redirectUri,
+    authMode: config.authMode ?? 'builtin',
+    verboseLogging: config.verboseLogging ?? false,
+    restartHandledByApp: config.restartHandledByApp ?? false,
+    maxFileProtectionLevel:
+      config.maxFileProtectionLevel ?? FileProtectionLevel.Complete,
+    // Throws on integration bugs that would otherwise leave data unprotected, so it is
+    // on in development and must never ship enabled.
+    strictMode: config.strictMode ?? __DEV__,
+    keychainGroupOverride: config.keychainGroupOverride ?? '',
+    telemetryEnabled: config.telemetryEnabled ?? true,
+    // Flattened because Codegen takes no nested optionals. '' means "leave the SDK's
+    // own default alone", which is not the same as a colour.
+    brandingBackground: config.branding?.background ?? '',
+    brandingForeground: config.branding?.foreground ?? '',
+    brandingAccent: config.branding?.accent ?? '',
+    brandingSecondaryBackground: config.branding?.secondaryBackground ?? '',
+    brandingSecondaryForeground: config.branding?.secondaryForeground ?? '',
+  });
+}
+
+/**
+ * SDK linked and platform prerequisites met. Gate the whole Intune path on this so a
+ * misbuilt binary degrades instead of crashing.
+ */
+export function isSupported(): Promise<boolean> {
+  return NativeIntune.isSupported();
+}
+
+/**
+ * Answerable before `configure`, on purpose — the app needs it to decide whether to
+ * prompt for a broker install.
+ *
+ * A false negative here usually means a missing manifest entry rather than a missing
+ * app: `LSApplicationQueriesSchemes` on iOS, `<queries>` on Android 11+.
+ */
+export async function getBrokerStatus(): Promise<BrokerStatus> {
+  return toBrokerStatus(await NativeIntune.getBrokerStatus());
+}
+
+/** Rejects with `E_NOT_NEEDED` when a broker is already present. */
+export function openBrokerInstall(): Promise<void> {
+  return NativeIntune.openBrokerInstall();
+}

package/src/api/policy.ts

@@ -0,0 +1,22 @@
+/**
+ * Reading policy, and reading the module's own state for a support bundle.
+ */
+
+import NativeIntune from '../NativeIntune';
+import { strRecord, toPolicySnapshot } from '../internal/decode';
+import type { Diagnostics, PolicySnapshot } from '../types';
+
+/**
+ * For adapting your own UI — hiding an export button, disabling a share sheet.
+ *
+ * **PIN prompts, screenshot blocking and encryption are enforced inside the SDK and
+ * never surface here.** Do not attempt to implement enforcement from these booleans.
+ */
+export async function getPolicy(): Promise<PolicySnapshot> {
+  return toPolicySnapshot(await NativeIntune.getPolicy());
+}
+
+/** Safe to attach to a support ticket: no tokens, no UPNs. */
+export async function getDiagnostics(): Promise<Diagnostics> {
+  return strRecord(await NativeIntune.getDiagnostics());
+}

package/src/api/tokenProvider.ts

@@ -0,0 +1,80 @@
+/**
+ * The MAM service token bridge (SPEC §13.4).
+ *
+ * The SDK asks for this token on a background thread, including on its own retry
+ * schedule when no JS call is in flight — which is why it is a registration rather than
+ * a callback parameter on `enroll`.
+ *
+ * The token never leaves the module: the provider's answer goes to native, native hands
+ * it to the SDK, and it is never logged or returned to JS (CLAUDE.md rule 9).
+ */
+
+import NativeIntune from '../NativeIntune';
+import { emitter } from '../internal/emitter';
+import { str } from '../internal/decode';
+import type { TokenProvider, TokenRequest } from '../types';
+
+let tokenProvider: TokenProvider | null = null;
+
+/**
+ * Registers the provider for `authMode: 'external'`. Return `null` from it to say
+ * "cannot get a token right now" — the SDK treats that as needing authorization rather
+ * than as a hard failure.
+ */
+export function setTokenProvider(provider: TokenProvider | null): void {
+  tokenProvider = provider;
+}
+
+/**
+ * Subscribed at import time, not from `setTokenProvider`.
+ *
+ * If nothing answers, the SDK waits until the native timeout — 45s on iOS, and on
+ * Android that is a *held background thread*. Replying "no provider" immediately turns a
+ * stall into a fast, named failure.
+ */
+emitter.addListener('tokenRequest', (raw: object) => {
+  const r = raw as Record<string, unknown>;
+  const requestId = str(r.requestId);
+  const request: TokenRequest = {
+    resourceId: str(r.resourceId),
+    tenantId: str(r.tenantId),
+    authority: str(r.authority),
+    accountId: str(r.accountId),
+  };
+
+  const active = tokenProvider;
+  if (active === null) {
+    NativeIntune.rejectToken({
+      requestId,
+      reason:
+        "No token provider is registered. In authMode 'external' the app must call " +
+        'setTokenProvider() before enrolling.',
+    });
+    return;
+  }
+
+  const respond = async () => {
+    try {
+      const token = await active(request);
+      if (typeof token === 'string' && token.length > 0) {
+        NativeIntune.resolveToken({ requestId, token });
+      } else {
+        NativeIntune.rejectToken({
+          requestId,
+          reason: 'token provider returned no token',
+        });
+      }
+    } catch (e) {
+      // The message reaches getDiagnostics and support logs, so pass the message and not
+      // the error object — a nested response body can carry a token.
+      NativeIntune.rejectToken({
+        requestId,
+        reason: e instanceof Error ? e.message : 'token provider threw',
+      });
+    }
+  };
+
+  // Nothing upstream can observe this promise: the SDK is waiting on the native side,
+  // and every path above already answers it.
+  respond().catch(() => {});
+});

package/src/index.ts

@@ -0,0 +1,127 @@
+/**
+ * Public API for react-native-intune. See SPEC §13 for the reference — a method that
+ * exists here but not there does not exist, and the two change in the same commit.
+ *
+ * This file is deliberately only a surface. The work is one directory down:
+ *
+ * ```
+ * src/
+ *   NativeIntune.ts        Codegen spec — the only file Codegen reads, deliberately loose
+ *   types.ts               every public type and enum
+ *   api/
+ *     lifecycle.ts         configure, isSupported, broker presence
+ *     auth.ts              sign-in, tokens for your own API   (authMode 'builtin')
+ *     enrollment.ts        enroll, getState, reset
+ *     policy.ts            getPolicy, getDiagnostics
+ *     events.ts            subscriptions
+ *     tokenProvider.ts     the MAM service token bridge       (authMode 'external')
+ *   internal/
+ *     decode.ts            bridge Object -> typed, with deliberate fallbacks
+ *     errors.ts            IntuneError and the accountId guard
+ *     emitter.ts           the single NativeEventEmitter
+ * ```
+ *
+ * Both import styles work and neither is preferred:
+ *
+ * ```ts
+ * import Intune from 'react-native-intune';          Intune.configure(...)
+ * import { configure } from 'react-native-intune';   configure(...)
+ * ```
+ */
+
+export * from './types';
+export { IntuneError } from './internal/errors';
+
+import {
+  configure,
+  getBrokerStatus,
+  isSupported,
+  openBrokerInstall,
+} from './api/lifecycle';
+import {
+  acquireToken,
+  getAccounts,
+  signIn,
+  signInAndEnroll,
+  signInSilent,
+  signOut,
+} from './api/auth';
+import {
+  enroll,
+  enrollInteractive,
+  getState,
+  reset,
+  setResetHandler,
+} from './api/enrollment';
+import { getDiagnostics, getPolicy } from './api/policy';
+import {
+  onBrokerStatusChanged,
+  onEnrollmentResult,
+  onPolicyChanged,
+  onRestartRequired,
+  onUnenrollmentResult,
+  onWipeRequested,
+} from './api/events';
+import { setTokenProvider } from './api/tokenProvider';
+
+export {
+  // setup
+  configure,
+  isSupported,
+  getBrokerStatus,
+  openBrokerInstall,
+  // auth — authMode 'builtin'
+  signIn,
+  signInSilent,
+  signInAndEnroll,
+  acquireToken,
+  getAccounts,
+  signOut,
+  // enrollment and reset
+  enroll,
+  enrollInteractive,
+  getState,
+  reset,
+  setResetHandler,
+  // policy
+  getPolicy,
+  getDiagnostics,
+  // token bridge — authMode 'external'
+  setTokenProvider,
+  // events
+  onEnrollmentResult,
+  onUnenrollmentResult,
+  onPolicyChanged,
+  onWipeRequested,
+  onRestartRequired,
+  onBrokerStatusChanged,
+};
+
+const Intune = {
+  configure,
+  isSupported,
+  getBrokerStatus,
+  openBrokerInstall,
+  signIn,
+  signInSilent,
+  signInAndEnroll,
+  acquireToken,
+  getAccounts,
+  signOut,
+  enroll,
+  enrollInteractive,
+  getState,
+  reset,
+  setResetHandler,
+  getPolicy,
+  getDiagnostics,
+  setTokenProvider,
+  onEnrollmentResult,
+  onUnenrollmentResult,
+  onPolicyChanged,
+  onWipeRequested,
+  onRestartRequired,
+  onBrokerStatusChanged,
+} as const;
+
+export default Intune;