@sparkvault/sdk-mobile 0.1.3

package/README.md

@@ -0,0 +1,186 @@
+# SparkVault Mobile SDK
+
+Mobile SDK for SparkVault Identity, vault, folder, and ingot workflows.
+
+## Install
+
+```bash
+npm install @sparkvault/sdk-mobile
+```
+
+## Create a Client
+
+```typescript
+import * as FileSystem from 'expo-file-system/legacy';
+import { createSparkVaultMobileClient } from '@sparkvault/sdk-mobile';
+
+export const sparkVault = createSparkVaultMobileClient({
+  tokenStorage,
+  apiBaseUrl: 'https://api.sparkvault.com/v1',
+  identityBaseUrl: 'https://api.sparkvault.com/v1/apps/identity',
+  identityAccountId: 'acc_00000000000000000000000000000000',
+  userAgent: 'SparkVault/1.0.0 (Mobile)',
+  fetch: xhrFetch,
+  fileReader: {
+    readAsBase64: (fileUri, { position, length }) =>
+      FileSystem.readAsStringAsync(fileUri, {
+        encoding: 'base64',
+        position,
+        length,
+      }),
+  },
+  fileDownloader: {
+    download: async (url, fileUri, options) => {
+      const resumable = FileSystem.createDownloadResumable(
+        url,
+        fileUri,
+        {},
+        progress => options?.onProgress?.({
+          bytesWritten: progress.totalBytesWritten,
+          bytesTotal: progress.totalBytesExpectedToWrite || undefined,
+        })
+      );
+      const result = await resumable.downloadAsync();
+      return result ? { uri: result.uri, status: result.status, headers: result.headers } : null;
+    },
+    getInfo: async (fileUri) => {
+      const info = await FileSystem.getInfoAsync(fileUri);
+      return { exists: info.exists, sizeBytes: info.exists ? info.size : undefined };
+    },
+    delete: (fileUri) => FileSystem.deleteAsync(fileUri, { idempotent: true }),
+  },
+});
+```
+
+### Dependency contract
+
+The SDK depends on `tweetnacl` for Ed25519 Identity JWT verification and declares `react`/`react-native` as peer dependencies for the optional native Identity dialog. Platform behavior stays behind adapters so the SDK is portable across React Native runtimes.
+
+| Adapter | Required | Default if omitted |
+|---------|----------|--------------------|
+| `tokenStorage` | Yes | Throws at client construction |
+| `identityAccountId` | Yes (must start with `acc_`) | Throws at client construction |
+| `fetch` | No | Falls back to `globalThis.fetch`; throws if neither exists |
+| `fileReader` | Only for `ingots.uploadFromUri` | Throws on first upload-from-URI call |
+| `fileDownloader` | Only for `ingots.downloadToFile` | Throws on first file-download call |
+| `passkeyProvider` | Only for passkey sign-in UI | Passkey is hidden from the Identity dialog |
+| `logger` | No | No-op logger |
+
+## Modules
+
+- `auth`: Identity config, TOTP/passkey login, JWKS/JWT verification, Core exchange, signup completion, profile, and account APIs.
+- `vaults`: Vault CRUD, unseal/seal, sharing, access retention, and public upload settings.
+- `folders`: Folder CRUD, breadcrumbs, folder moves, and ingot moves.
+- `ingots`: List/search/get, URI streaming upload/replace, rename/delete, sharing, access logs, and SDK-managed file downloads.
+- `health`: Root API availability checks.
+- `sparks`: SparkSync spark list/read/create operations.
+- `entropy`: HSM-backed entropy generation.
+- `pushTokens`: Expo push-token registration/removal.
+- `billing`: Account balance.
+
+## Identity Dialog
+
+`SparkVaultIdentityDialog` is the mobile equivalent of the web SDK Identity popup. It fetches Identity App config, renders email/phone input from `allowedIdentityTypes`, offers enabled mobile-supported methods (`passkey`, `totp_email`, `totp_sms`, `totp_voice`), applies configured branding and light/dark mode, and returns the raw signed Identity JWT plus JWKS metadata.
+
+```tsx
+import * as Passkey from 'react-native-passkeys';
+import {
+  SparkVaultIdentityDialog,
+  type MobilePasskeyProvider,
+} from '@sparkvault/sdk-mobile/identity-dialog';
+
+const passkeyProvider: MobilePasskeyProvider = {
+  isSupported: () => Passkey.isSupported(),
+  authenticate: async (options) => {
+    const credential = await Passkey.get({
+      challenge: options.challenge,
+      timeout: options.timeout,
+      rpId: options.rpId,
+      allowCredentials: options.allowCredentials,
+      userVerification: options.userVerification,
+    });
+
+    return credential
+      ? {
+          id: credential.id,
+          rawId: credential.rawId,
+          type: 'public-key',
+          response: {
+            clientDataJSON: credential.response.clientDataJSON,
+            authenticatorData: credential.response.authenticatorData,
+            signature: credential.response.signature,
+          },
+        }
+      : null;
+  },
+};
+
+<SparkVaultIdentityDialog
+  client={sparkVault}
+  visible={visible}
+  passkeyProvider={passkeyProvider}
+  onCancel={() => setVisible(false)}
+  onSuccess={async (result) => {
+    await sparkVault.auth.verifyIdentityToken(result.token, { jwks: result.jwks });
+    const session = await sparkVault.auth.exchangeIdentityToken(result.token);
+    // Continue only after local verification and Core exchange succeed.
+  }}
+/>;
+```
+
+Client-side JWT verification is an app integrity gate. Third-party backends must still verify the token server-side with the JWKS endpoint before creating their own sessions.
+
+## Health Check
+
+```typescript
+const status = await sparkVault.health.check();
+const online = await sparkVault.health.isOnline();
+```
+
+## Ingot Upload
+
+```typescript
+const session = await sparkVault.vaults.unseal(vaultId, { vmk });
+
+await sparkVault.ingots.uploadFromUri({
+  vaultId,
+  vat: session.vat,
+  fileUri,
+  fileSize,
+  name: 'receipt.pdf',
+  contentType: 'application/pdf',
+  onProgress: (uploaded, total) => console.log(uploaded / total),
+});
+
+await sparkVault.ingots.replaceFromUri({
+  vaultId,
+  ingotId,
+  vat: session.vat,
+  fileUri,
+  fileSize,
+  name: 'receipt.pdf',
+  contentType: 'application/pdf',
+});
+```
+
+Uploads use Forge with tus v1.0.0 and read file chunks through the configured
+`fileReader` adapter. Generated content should be staged to a file URI first so
+all uploads use the same streaming path.
+
+## Ingot Download
+
+```typescript
+const result = await sparkVault.ingots.downloadToFile({
+  vaultId,
+  ingotId,
+  vat: session.vat,
+  fileUri: cacheFileUri,
+  expectedSizeBytes,
+  onProgress: (downloaded, total) => console.log(downloaded / total),
+});
+```
+
+Downloads use the configured `fileDownloader` adapter for one canonical
+streaming path across every supported file size. Production adapters should
+honor `abortSignal` and `timeoutMs`, and should throw on transport failure
+instead of writing an error response as a successful file.

package/dist/auth.d.ts

@@ -0,0 +1,74 @@
+import { type ResolvedMobileConfig } from './config.js';
+import type { MobileHttpClient } from './http.js';
+import type { CompleteSignupRequest, CompleteSignupResponse, IdentityConfig, IdentityJwks, IdentityTokenClaims, IdentityType, IdentityVerifyResult, PasskeyAuthChallenge, PasskeyCredential, PasskeyRegisterChallenge, PasskeySession, PasskeyStatus, PinVerifyRequest, PinVerifyResponse, RequestPinRequest, RequestPinResponse, SendTotpRequest, SparkVaultAccount, SparkVaultUser, VerifyTotpRequest } from './types.js';
+export declare class MobileAuthClient {
+    private readonly config;
+    private readonly http;
+    private configCache;
+    private jwksCache;
+    private jwksCachedAt;
+    constructor(config: ResolvedMobileConfig, http: MobileHttpClient);
+    getJwksUri(): string;
+    getConfig(): Promise<IdentityConfig>;
+    preloadConfig(): void;
+    isConfigPreloaded(): boolean;
+    getJwks(options?: {
+        forceRefresh?: boolean;
+    }): Promise<IdentityJwks>;
+    verifyIdentityToken(token: string, options?: {
+        jwks?: IdentityJwks;
+        audience?: string;
+        clockSkewSeconds?: number;
+    }): Promise<IdentityTokenClaims>;
+    private resolveJwk;
+    private tryFindJwk;
+    sendTotp(request: SendTotpRequest): Promise<RequestPinResponse>;
+    requestPin(request: RequestPinRequest): Promise<RequestPinResponse>;
+    verifyTotp(request: VerifyTotpRequest): Promise<IdentityVerifyResult>;
+    verifyPin(request: PinVerifyRequest): Promise<PinVerifyResponse>;
+    completeSignup(signupToken: string, request: CompleteSignupRequest): Promise<CompleteSignupResponse>;
+    signup(params: {
+        signup_token: string;
+        organization_name: string;
+        full_name?: string;
+    }): Promise<CompleteSignupResponse>;
+    checkPasskeyStatus(identity: string, identityType?: IdentityType): Promise<{
+        hasPasskey: boolean;
+    }>;
+    getPasskeyAuthOptions(identity: string, identityType?: IdentityType): Promise<PasskeyAuthChallenge>;
+    completePasskeyAuthentication(credential: PasskeyCredential, session: PasskeySession): Promise<IdentityVerifyResult>;
+    verifyPasskeyAuth(credential: PasskeyCredential, session: PasskeySession): Promise<PinVerifyResponse>;
+    getPasskeyRegisterOptions(params?: {
+        email?: string;
+        deviceName?: string;
+    }): Promise<PasskeyRegisterChallenge>;
+    registerPasskey(credential: PasskeyCredential, session: PasskeySession): Promise<{
+        success: boolean;
+        credential_id: string;
+    }>;
+    getMyPasskeyStatus(): Promise<PasskeyStatus>;
+    getProfile(): Promise<SparkVaultUser>;
+    updateProfile(updates: {
+        name?: string;
+    }): Promise<SparkVaultUser>;
+    getAccount(): Promise<SparkVaultAccount>;
+    revokeRefreshToken(refreshToken?: string): Promise<void>;
+    logout(options?: {
+        revoke?: boolean;
+        clearTokens?: boolean;
+    }): Promise<void>;
+    exchangeIdentityToken(identityToken: string): Promise<PinVerifyResponse>;
+    private storeSession;
+    private verifyTotpWithRetryErrors;
+    private startConfigLoad;
+    private toIdentityVerifyResult;
+    private decodeIdentityTokenClaims;
+    private getIdentity;
+    private postIdentity;
+    private identityHeaders;
+    private identityLookupBody;
+    private normalizeIdentity;
+    private selectJwk;
+    private isIdentityTokenClaims;
+    private getStoredUserEmail;
+}