@sparkvault/sdk-mobile 0.1.3

package/src/auth.ts

@@ -0,0 +1,707 @@
+import { identityUrl, type ResolvedMobileConfig } from './config.js';
+import { base64UrlToBytes, base64UrlToUtf8, utf8ToBytes } from './encoding.js';
+import { SparkVaultAuthenticationError, SparkVaultMobileError, SparkVaultValidationError } from './errors.js';
+import type { MobileHttpClient } from './http.js';
+import type {
+  ApiErrorBody,
+  CompleteSignupRequest,
+  CompleteSignupResponse,
+  IdentityConfig,
+  IdentityJwks,
+  IdentityTokenClaims,
+  IdentityType,
+  IdentityVerifyResult,
+  IdentitySessionResponse,
+  PasskeyAuthChallenge,
+  PasskeyCredential,
+  PasskeyRegisterChallenge,
+  PasskeySession,
+  PasskeyStatus,
+  PinVerifyRequest,
+  PinVerifyResponse,
+  RequestPinRequest,
+  RequestPinResponse,
+  SendTotpRequest,
+  SparkVaultAccount,
+  SparkVaultUser,
+  VerifyTotpRequest,
+} from './types.js';
+import nacl from 'tweetnacl';
+
+interface IdentityVerificationResponse {
+  verified: boolean;
+  token?: string;
+  identity?: string;
+  identity_type?: IdentityType;
+  method?: string;
+  redirect?: string;
+  kindling?: string;
+  expires_at?: number;
+  retry_after?: number;
+}
+
+interface IdentityPasskeyCompletionResponse {
+  verified?: boolean;
+  token: string;
+  identity: string;
+  identity_type: IdentityType;
+  method: string;
+  redirect?: string;
+}
+
+interface JwtHeader {
+  alg: string;
+  kid?: string;
+}
+
+const JWKS_CACHE_TTL_MS = 10 * 60 * 1000;
+
+export class MobileAuthClient {
+  private readonly config: ResolvedMobileConfig;
+  private readonly http: MobileHttpClient;
+  private configCache: Promise<IdentityConfig> | null = null;
+  private jwksCache: Promise<IdentityJwks> | null = null;
+  private jwksCachedAt = 0;
+
+  constructor(config: ResolvedMobileConfig, http: MobileHttpClient) {
+    this.config = config;
+    this.http = http;
+  }
+
+  getJwksUri(): string {
+    return identityUrl(this.config, '/.well-known/jwks.json');
+  }
+
+  async getConfig(): Promise<IdentityConfig> {
+    const configRequest = this.configCache ?? this.startConfigLoad();
+
+    try {
+      return await configRequest;
+    } catch (error) {
+      this.configCache = null;
+      throw error;
+    }
+  }
+
+  preloadConfig(): void {
+    if (!this.configCache) {
+      this.startConfigLoad().catch(() => undefined);
+    }
+  }
+
+  isConfigPreloaded(): boolean {
+    return this.configCache !== null;
+  }
+
+  async getJwks(options: { forceRefresh?: boolean } = {}): Promise<IdentityJwks> {
+    const now = Date.now();
+    const expired = now - this.jwksCachedAt > JWKS_CACHE_TTL_MS;
+    if (!this.jwksCache || expired || options.forceRefresh) {
+      this.jwksCache = this.getIdentity<IdentityJwks>('/.well-known/jwks.json');
+      this.jwksCachedAt = now;
+    }
+
+    try {
+      return await this.jwksCache;
+    } catch (error) {
+      this.jwksCache = null;
+      this.jwksCachedAt = 0;
+      throw error;
+    }
+  }
+
+  async verifyIdentityToken(
+    token: string,
+    options: {
+      jwks?: IdentityJwks;
+      audience?: string;
+      clockSkewSeconds?: number;
+    } = {}
+  ): Promise<IdentityTokenClaims> {
+    if (!token || typeof token !== 'string') {
+      throw new SparkVaultValidationError('Identity token is required', { field: 'token' });
+    }
+
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+      throw new SparkVaultValidationError('Invalid identity token format');
+    }
+
+    const [headerPart, payloadPart, signaturePart] = parts;
+    let header: JwtHeader;
+    let claims: IdentityTokenClaims;
+
+    try {
+      header = JSON.parse(base64UrlToUtf8(headerPart)) as JwtHeader;
+      const parsedClaims = JSON.parse(base64UrlToUtf8(payloadPart)) as unknown;
+      if (!this.isIdentityTokenClaims(parsedClaims)) {
+        throw new Error('Invalid claims');
+      }
+      claims = parsedClaims;
+    } catch {
+      throw new SparkVaultValidationError('Invalid identity token payload');
+    }
+
+    if (header.alg !== 'EdDSA') {
+      throw new SparkVaultValidationError('Unsupported identity token algorithm', { alg: header.alg });
+    }
+
+    // Verify the signature BEFORE any claim is acted upon. JWKS is refreshed
+    // once on a kid miss so Identity App key rotation propagates without a
+    // process restart.
+    const jwk = await this.resolveJwk(header.kid, options.jwks);
+    const signatureValid = nacl.sign.detached.verify(
+      utf8ToBytes(`${headerPart}.${payloadPart}`),
+      base64UrlToBytes(signaturePart),
+      base64UrlToBytes(jwk.x)
+    );
+    if (!signatureValid) {
+      throw new SparkVaultAuthenticationError('Identity token signature is invalid');
+    }
+
+    const now = Math.floor(Date.now() / 1000);
+    const clockSkewSeconds = options.clockSkewSeconds ?? 60;
+    if (claims.exp + clockSkewSeconds < now) {
+      throw new SparkVaultValidationError('Identity token has expired');
+    }
+    if (claims.iat - clockSkewSeconds > now) {
+      throw new SparkVaultValidationError('Identity token was issued in the future');
+    }
+    if (claims.nbf !== undefined && claims.nbf - clockSkewSeconds > now) {
+      throw new SparkVaultValidationError('Identity token is not valid yet');
+    }
+    if (typeof claims.nbf === 'number' && claims.nbf > now + clockSkewSeconds) {
+      throw new SparkVaultValidationError('Identity token is not yet valid');
+    }
+
+    const expectedIssuer = `${this.config.identityBaseUrl}/${this.config.identityAccountId}`;
+    if (claims.iss !== expectedIssuer) {
+      throw new SparkVaultValidationError('Invalid identity token issuer', {
+        expected: expectedIssuer,
+        received: claims.iss,
+      });
+    }
+
+    const expectedAudience = options.audience ?? this.config.identityAccountId;
+    if (claims.aud !== expectedAudience) {
+      throw new SparkVaultValidationError('Invalid identity token audience', {
+        expected: expectedAudience,
+        received: claims.aud,
+      });
+    }
+
+    return claims;
+  }
+
+  private async resolveJwk(kid: string | undefined, providedJwks?: IdentityJwks): Promise<{ x: string }> {
+    if (providedJwks) {
+      return this.selectJwk(providedJwks, kid);
+    }
+    const jwks = await this.getJwks();
+    const match = this.tryFindJwk(jwks, kid);
+    if (match) {
+      return match;
+    }
+    // Cache miss for the requested kid: Identity App may have rotated keys.
+    // Force-refresh the JWKS exactly once and retry before failing.
+    const refreshed = await this.getJwks({ forceRefresh: true });
+    return this.selectJwk(refreshed, kid);
+  }
+
+  private tryFindJwk(jwks: IdentityJwks, kid?: string): { x: string } | null {
+    const key = kid
+      ? jwks.keys.find(candidate => candidate.kid === kid)
+      : jwks.keys.find(candidate => candidate.kty === 'OKP' && candidate.crv === 'Ed25519');
+    if (!key) return null;
+    if (key.kty !== 'OKP' || key.crv !== 'Ed25519' || typeof key.x !== 'string') {
+      return null;
+    }
+    return key;
+  }
+
+  async sendTotp(request: SendTotpRequest): Promise<RequestPinResponse> {
+    const identity = this.normalizeIdentity(request.identity, request.identityType);
+    const result = await this.postIdentity<{
+      kindling: string;
+      expires_at?: number;
+      retry_after?: number;
+    }>('/totp/send', {
+      recipient: identity,
+      method: request.method,
+    });
+
+    return {
+      kindling: result.kindling,
+      expires_at: result.expires_at ?? Math.floor(Date.now() / 1000) + 900,
+      retry_after: result.retry_after,
+      is_signup: false,
+    };
+  }
+
+  async requestPin(request: RequestPinRequest): Promise<RequestPinResponse> {
+    return this.sendTotp({
+      identity: request.email,
+      identityType: 'email',
+      method: 'email',
+    });
+  }
+
+  async verifyTotp(request: VerifyTotpRequest): Promise<IdentityVerifyResult> {
+    const verifyResult = await this.verifyTotpWithRetryErrors(request);
+    if (!verifyResult.verified || !verifyResult.token) {
+      if (verifyResult.kindling) {
+        const error = new SparkVaultMobileError('Invalid code. Please try again.', {
+          code: 400,
+          statusCode: 400,
+        });
+        (error as SparkVaultMobileError & { data?: unknown }).data = {
+          kindling: verifyResult.kindling,
+          expires_at: verifyResult.expires_at,
+        };
+        throw error;
+      }
+
+      throw new SparkVaultMobileError('Verification failed. Please request a new code.', {
+        code: 400,
+        statusCode: 400,
+      });
+    }
+
+    return this.toIdentityVerifyResult(verifyResult.token, {
+      identity: verifyResult.identity ?? request.recipient,
+      identityType: verifyResult.identity_type,
+      method: verifyResult.method,
+      redirect: verifyResult.redirect,
+    });
+  }
+
+  async verifyPin(request: PinVerifyRequest): Promise<PinVerifyResponse> {
+    const verifyResult = await this.verifyTotpWithRetryErrors(request);
+
+    if (!verifyResult.verified || !verifyResult.token) {
+      if (verifyResult.kindling) {
+        const error = new SparkVaultMobileError('Invalid code. Please try again.', {
+          code: 400,
+          statusCode: 400,
+        });
+        (error as SparkVaultMobileError & { data?: unknown }).data = {
+          kindling: verifyResult.kindling,
+          expires_at: verifyResult.expires_at,
+        };
+        throw error;
+      }
+
+      throw new SparkVaultMobileError('Verification failed. Please request a new code.', {
+        code: 400,
+        statusCode: 400,
+      });
+    }
+
+    return this.exchangeIdentityToken(verifyResult.token);
+  }
+
+  async completeSignup(
+    signupToken: string,
+    request: CompleteSignupRequest
+  ): Promise<CompleteSignupResponse> {
+    const response = await this.http.post<CompleteSignupResponse>(
+      '/auth/complete-signup',
+      request,
+      {
+        skipAuth: true,
+        headers: { Authorization: `Bearer ${signupToken}` },
+      }
+    );
+
+    await this.storeSession(response.data);
+    return response.data;
+  }
+
+  async signup(params: {
+    signup_token: string;
+    organization_name: string;
+    full_name?: string;
+  }): Promise<CompleteSignupResponse> {
+    return this.completeSignup(params.signup_token, {
+      organization_name: params.organization_name,
+      full_name: params.full_name,
+    });
+  }
+
+  async checkPasskeyStatus(identity: string, identityType?: IdentityType): Promise<{ hasPasskey: boolean }> {
+    try {
+      const result = await this.postIdentity<{ has_passkey: boolean }>(
+        '/passkey/check',
+        this.identityLookupBody(identity, identityType)
+      );
+      return { hasPasskey: Boolean(result.has_passkey) };
+    } catch {
+      return { hasPasskey: false };
+    }
+  }
+
+  async getPasskeyAuthOptions(identity: string, identityType?: IdentityType): Promise<PasskeyAuthChallenge> {
+    return this.postIdentity<PasskeyAuthChallenge>('/passkey/verify', this.identityLookupBody(identity, identityType));
+  }
+
+  async completePasskeyAuthentication(
+    credential: PasskeyCredential,
+    session: PasskeySession
+  ): Promise<IdentityVerifyResult> {
+    const result = await this.postIdentity<IdentityPasskeyCompletionResponse>(
+      '/passkey/verify/complete',
+      { session, credential }
+    );
+
+    if (result.verified === false || !result.token) {
+      throw new SparkVaultAuthenticationError('Passkey verification failed');
+    }
+
+    return this.toIdentityVerifyResult(result.token, {
+      identity: result.identity,
+      identityType: result.identity_type,
+      method: result.method,
+      redirect: result.redirect,
+    });
+  }
+
+  async verifyPasskeyAuth(
+    credential: PasskeyCredential,
+    session: PasskeySession
+  ): Promise<PinVerifyResponse> {
+    const result = await this.completePasskeyAuthentication(credential, session);
+    return this.exchangeIdentityToken(result.token);
+  }
+
+  async getPasskeyRegisterOptions(params: { email?: string; deviceName?: string } = {}): Promise<PasskeyRegisterChallenge> {
+    const email = params.email ?? await this.getStoredUserEmail();
+    if (!email) {
+      throw new SparkVaultAuthenticationError('You must be signed in to register a passkey');
+    }
+
+    return this.postIdentity<PasskeyRegisterChallenge>('/passkey/register', {
+      email: email.trim().toLowerCase(),
+      device_name: params.deviceName ?? this.config.userAgent,
+    });
+  }
+
+  async registerPasskey(
+    credential: PasskeyCredential,
+    session: PasskeySession
+  ): Promise<{ success: boolean; credential_id: string }> {
+    const result = await this.postIdentity<IdentityPasskeyCompletionResponse>(
+      '/passkey/register/complete',
+      { session, credential }
+    );
+
+    const success = result.verified !== false;
+
+    if (success && this.config.tokenStorage.getUser && this.config.tokenStorage.setUser) {
+      const user = await this.config.tokenStorage.getUser<SparkVaultUser>();
+      if (user) {
+        await this.config.tokenStorage.setUser<SparkVaultUser>({ ...user, has_passkey: true });
+      }
+    }
+
+    return { success, credential_id: credential.id };
+  }
+
+  async getMyPasskeyStatus(): Promise<PasskeyStatus> {
+    const email = await this.getStoredUserEmail();
+    if (!email) {
+      return { has_passkey: false };
+    }
+    const { hasPasskey } = await this.checkPasskeyStatus(email, 'email');
+    return { has_passkey: hasPasskey };
+  }
+
+  async getProfile(): Promise<SparkVaultUser> {
+    const response = await this.http.get<SparkVaultUser>('/profile');
+    if (this.config.tokenStorage.setUser) {
+      await this.config.tokenStorage.setUser(response.data);
+    }
+    return response.data;
+  }
+
+  async updateProfile(updates: { name?: string }): Promise<SparkVaultUser> {
+    const response = await this.http.put<SparkVaultUser>('/profile', updates);
+    if (this.config.tokenStorage.setUser) {
+      await this.config.tokenStorage.setUser(response.data);
+    }
+    return response.data;
+  }
+
+  async getAccount(): Promise<SparkVaultAccount> {
+    const response = await this.http.get<SparkVaultAccount>('/account');
+    if (this.config.tokenStorage.setAccount) {
+      await this.config.tokenStorage.setAccount(response.data);
+    }
+    return response.data;
+  }
+
+  async revokeRefreshToken(refreshToken?: string): Promise<void> {
+    const token = refreshToken ?? await this.config.tokenStorage.getRefreshToken();
+    if (!token) return;
+
+    await this.http.post('/auth/logout', { refresh_token: token }).catch(err => {
+      this.config.logger.warn('Logout API call failed', { error: String(err) });
+    });
+  }
+
+  async logout(options: { revoke?: boolean; clearTokens?: boolean } = {}): Promise<void> {
+    if (options.revoke !== false) {
+      await this.revokeRefreshToken();
+    }
+    if (options.clearTokens !== false) {
+      await this.config.tokenStorage.clearTokens();
+    }
+  }
+
+  async exchangeIdentityToken(identityToken: string): Promise<PinVerifyResponse> {
+    const sessionResponse = await this.http.post<IdentitySessionResponse>(
+      '/auth/identity/verify',
+      { token: identityToken },
+      { skipAuth: true }
+    );
+
+    const session = sessionResponse.data;
+    if (session.user) {
+      await this.storeSession(session);
+      return {
+        access_token: session.access_token,
+        refresh_token: session.refresh_token,
+        token_type: session.token_type ?? 'Bearer',
+        expires_in: session.expires_in ?? 3600,
+        user: session.user,
+      };
+    }
+
+    return {
+      verified: true,
+      needs_signup_info: true,
+      signup_token: session.access_token,
+      expires_at: Math.floor(Date.now() / 1000) + (session.expires_in ?? 3600),
+    };
+  }
+
+  private async storeSession(session: {
+    access_token: string;
+    refresh_token: string;
+    user?: SparkVaultUser | null;
+    account?: SparkVaultAccount | null;
+  }): Promise<void> {
+    if (!session.access_token || !session.refresh_token) {
+      throw new SparkVaultValidationError('Invalid session response from SparkVault');
+    }
+
+    if (this.config.tokenStorage.setTokens) {
+      await this.config.tokenStorage.setTokens(session.access_token, session.refresh_token);
+    } else {
+      await Promise.all([
+        this.config.tokenStorage.setAccessToken(session.access_token),
+        this.config.tokenStorage.setRefreshToken(session.refresh_token),
+      ]);
+    }
+
+    const writes: Promise<void>[] = [];
+    if (session.user && this.config.tokenStorage.setUser) {
+      writes.push(this.config.tokenStorage.setUser(session.user));
+    }
+    if (session.account && this.config.tokenStorage.setAccount) {
+      writes.push(this.config.tokenStorage.setAccount(session.account));
+    }
+    await Promise.all(writes);
+  }
+
+  private async verifyTotpWithRetryErrors(request: VerifyTotpRequest): Promise<IdentityVerificationResponse> {
+    try {
+      return await this.postIdentity<IdentityVerificationResponse>('/totp/verify', {
+        kindling: request.kindling,
+        pin: request.pin,
+        recipient: request.recipient.trim().toLowerCase(),
+      });
+    } catch (err) {
+      const apiError = err as SparkVaultMobileError & {
+        data?: { kindling?: string; expires_at?: number };
+      };
+      const message = apiError.message || 'Verification failed';
+      const code = apiError.statusCode ?? apiError.code;
+
+      if (
+        code === 403 ||
+        code === 410 ||
+        message.toLowerCase().includes('burned') ||
+        message.toLowerCase().includes('expired')
+      ) {
+        throw new SparkVaultMobileError('Verification session expired. Please request a new code.', {
+          code: code || 410,
+          statusCode: typeof code === 'number' ? code : 410,
+        });
+      }
+
+      throw apiError;
+    }
+  }
+
+  private startConfigLoad(): Promise<IdentityConfig> {
+    const request = this.getIdentity<IdentityConfig>('/config').catch((error: unknown) => {
+      this.configCache = null;
+      throw error;
+    });
+    this.configCache = request;
+    return request;
+  }
+
+  private toIdentityVerifyResult(
+    token: string,
+    details: {
+      identity?: string;
+      identityType?: IdentityType;
+      method?: string;
+      redirect?: string;
+    }
+  ): IdentityVerifyResult {
+    const claims = this.decodeIdentityTokenClaims(token);
+    return {
+      token,
+      identity: details.identity ?? claims.identity,
+      identityType: details.identityType ?? claims.identity_type,
+      method: details.method ?? claims.method,
+      redirect: details.redirect,
+      jwksUri: this.getJwksUri(),
+    };
+  }
+
+  private decodeIdentityTokenClaims(token: string): IdentityTokenClaims {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+      throw new SparkVaultValidationError('Invalid identity token format');
+    }
+
+    try {
+      const payload = JSON.parse(base64UrlToUtf8(parts[1])) as unknown;
+      if (!this.isIdentityTokenClaims(payload)) {
+        throw new Error('Invalid claims');
+      }
+      return payload;
+    } catch {
+      throw new SparkVaultValidationError('Invalid identity token payload');
+    }
+  }
+
+  private async getIdentity<T>(path: string): Promise<T> {
+    const response = await this.config.fetch(identityUrl(this.config, path), {
+      method: 'GET',
+      headers: this.identityHeaders(),
+      timeoutMs: this.config.timeoutMs,
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({} as ApiErrorBody));
+      const message = errorBody.error?.message ?? errorBody.message ?? 'Identity request failed';
+      throw new SparkVaultMobileError(message, {
+        code: errorBody.error?.code ?? response.status,
+        statusCode: response.status,
+        details: errorBody.error?.details,
+        meta: errorBody.meta,
+      });
+    }
+
+    const data = await response.json();
+    return (data.data ?? data) as T;
+  }
+
+  private async postIdentity<T>(
+    path: string,
+    body: Record<string, unknown>,
+    options: { bearerToken?: string } = {}
+  ): Promise<T> {
+    const headers = this.identityHeaders(options.bearerToken);
+    const response = await this.config.fetch(identityUrl(this.config, path), {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      timeoutMs: this.config.timeoutMs,
+    });
+
+    if (!response.ok) {
+      const errorBody = await response.json().catch(() => ({} as ApiErrorBody));
+      const message = errorBody.error?.message ?? errorBody.message ?? 'Identity verification failed';
+      const error = new SparkVaultMobileError(message, {
+        code: errorBody.error?.code ?? response.status,
+        statusCode: response.status,
+        details: errorBody.error?.details,
+        meta: errorBody.meta,
+      });
+      (error as SparkVaultMobileError & { data?: unknown }).data = errorBody.data ?? errorBody;
+      throw error;
+    }
+
+    const data = await response.json();
+    return (data.data ?? data) as T;
+  }
+
+  private identityHeaders(bearerToken?: string): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      'User-Agent': this.config.userAgent,
+    };
+    if (bearerToken) {
+      headers.Authorization = `Bearer ${bearerToken}`;
+    }
+    return headers;
+  }
+
+  private identityLookupBody(identity: string, identityType?: IdentityType): Record<string, string> {
+    const inferredType = identityType ?? (identity.includes('@') ? 'email' : 'phone');
+    const normalized = this.normalizeIdentity(identity, inferredType);
+    return inferredType === 'phone' ? { phone: normalized } : { email: normalized };
+  }
+
+  private normalizeIdentity(identity: string, identityType: IdentityType): string {
+    const trimmed = identity.trim();
+    if (!trimmed) {
+      throw new SparkVaultValidationError('Identity is required', { field: 'identity' });
+    }
+    return identityType === 'email' ? trimmed.toLowerCase() : trimmed;
+  }
+
+  private selectJwk(jwks: IdentityJwks, kid?: string): { x: string } {
+    const key = kid
+      ? jwks.keys.find(candidate => candidate.kid === kid)
+      : jwks.keys.find(candidate => candidate.kty === 'OKP' && candidate.crv === 'Ed25519');
+
+    if (!key) {
+      throw new SparkVaultValidationError('No matching Identity JWKS key was found', { kid });
+    }
+    if (key.kty !== 'OKP' || key.crv !== 'Ed25519' || typeof key.x !== 'string') {
+      throw new SparkVaultValidationError('Identity JWKS key is not an Ed25519 public key');
+    }
+    return key;
+  }
+
+  private isIdentityTokenClaims(value: unknown): value is IdentityTokenClaims {
+    if (typeof value !== 'object' || value === null) return false;
+    const claims = value as Record<string, unknown>;
+    return (
+      typeof claims.iss === 'string' &&
+      typeof claims.sub === 'string' &&
+      typeof claims.aud === 'string' &&
+      typeof claims.exp === 'number' &&
+      typeof claims.iat === 'number' &&
+      (claims.nbf === undefined || typeof claims.nbf === 'number') &&
+      (claims.jti === undefined || typeof claims.jti === 'string') &&
+      typeof claims.identity === 'string' &&
+      (claims.identity_type === 'email' || claims.identity_type === 'phone') &&
+      typeof claims.verified_at === 'number' &&
+      typeof claims.method === 'string'
+    );
+  }
+
+  private async getStoredUserEmail(): Promise<string | null> {
+    if (!this.config.tokenStorage.getUser) return null;
+    const user = await this.config.tokenStorage.getUser<SparkVaultUser>();
+    return user?.email ?? null;
+  }
+}