@sparkvault/sdk-mobile 0.1.3

package/src/types.ts

@@ -0,0 +1,487 @@
+export interface ApiMeta {
+  request_id: string;
+  response_ms: number;
+  timestamp: number;
+  api_version: string;
+  balance?: string;
+  quota?: {
+    limit: number;
+    used: number;
+    remaining: number;
+    resets_at: number;
+  };
+}
+
+export interface ApiResponse<T> {
+  data: T;
+  meta: ApiMeta;
+}
+
+export interface ApiErrorBody {
+  error?: {
+    code?: number | string;
+    message?: string;
+    details?: Record<string, unknown>;
+  };
+  message?: string;
+  data?: unknown;
+  meta?: ApiMeta;
+}
+
+export interface RateLimitInfo {
+  limit: number;
+  remaining: number;
+  reset: number;
+}
+
+export interface SparkVaultUser {
+  user_id: string;
+  email: string;
+  name?: string;
+  role: 'admin' | 'engineer' | 'viewer';
+  has_passkey?: boolean;
+  created_at: number;
+}
+
+export interface SparkVaultAccount {
+  account_id: string;
+  organization_name: string;
+  email: string;
+  status: 'active' | 'suspended';
+  balance: string;
+  logo_url?: string;
+  logo_dark_url?: string;
+  created_at: number;
+}
+
+export type IdentityType = 'email' | 'phone';
+
+export type IdentityMethodId =
+  | 'totp_email'
+  | 'totp_sms'
+  | 'totp_voice'
+  | 'passkey'
+  | 'sparklink'
+  | 'social_google'
+  | 'social_apple'
+  | 'social_microsoft'
+  | 'social_github'
+  | 'social_facebook'
+  | 'social_linkedin'
+  | 'enterprise_okta'
+  | 'enterprise_entra'
+  | 'enterprise_onelogin'
+  | 'enterprise_ping'
+  | 'enterprise_jumpcloud';
+
+export interface IdentityBranding {
+  companyName: string | null;
+  logoLight: string | null;
+  logoDark: string | null;
+  backdrop_blur?: boolean;
+  themeMode?: 'light' | 'dark';
+}
+
+export interface IdentityConfig {
+  accountId: string;
+  branding?: IdentityBranding;
+  allowedIdentityTypes?: IdentityType[];
+  methods: IdentityMethodId[];
+  wsDomain?: string;
+}
+
+export interface IdentityJwk {
+  kty: 'OKP';
+  crv: 'Ed25519';
+  x: string;
+  kid?: string;
+  alg?: 'EdDSA' | string;
+  use?: string;
+}
+
+export interface IdentityJwks {
+  keys: IdentityJwk[];
+}
+
+export interface IdentityTokenClaims {
+  iss: string;
+  sub: string;
+  aud: string;
+  exp: number;
+  iat: number;
+  nbf?: number;
+  jti?: string;
+  identity: string;
+  identity_type: IdentityType;
+  verified_at: number;
+  method: string;
+}
+
+export interface IdentityVerifyResult {
+  token: string;
+  identity: string;
+  identityType: IdentityType;
+  method?: string;
+  redirect?: string;
+  jwksUri: string;
+  jwks?: IdentityJwks;
+}
+
+export interface SendTotpRequest {
+  identity: string;
+  identityType: IdentityType;
+  method: 'email' | 'sms' | 'voice';
+}
+
+export interface VerifyTotpRequest {
+  kindling: string;
+  pin: string;
+  recipient: string;
+}
+
+export interface RequestPinRequest {
+  email: string;
+  organization_name?: string;
+}
+
+export interface RequestPinResponse {
+  kindling: string;
+  expires_at: number;
+  retry_after?: number;
+  is_signup: boolean;
+}
+
+export interface PinVerifyRequest {
+  kindling: string;
+  pin: string;
+  recipient: string;
+  organization_name?: string;
+}
+
+export interface PinVerifyLoginResponse {
+  access_token: string;
+  refresh_token: string;
+  token_type: 'Bearer';
+  expires_in: number;
+  user: SparkVaultUser;
+}
+
+export interface PinVerifySignupPendingResponse {
+  verified: true;
+  needs_signup_info: true;
+  signup_token: string;
+  expires_at: number;
+}
+
+export type PinVerifyResponse = PinVerifyLoginResponse | PinVerifySignupPendingResponse;
+
+export interface CompleteSignupRequest {
+  organization_name: string;
+  full_name?: string;
+}
+
+export interface CompleteSignupResponse {
+  access_token: string;
+  refresh_token: string;
+  token_type?: 'Bearer';
+  expires_in?: number;
+  user: SparkVaultUser;
+  account: SparkVaultAccount;
+}
+
+export type PasskeySession = Record<string, unknown>;
+
+export interface PasskeyAuthOptions {
+  challenge: string;
+  timeout: number;
+  rpId: string;
+  allowCredentials?: {
+    id: string;
+    type: 'public-key';
+  }[];
+  userVerification: 'required' | 'preferred' | 'discouraged';
+}
+
+export interface PasskeyAuthChallenge {
+  options: PasskeyAuthOptions;
+  session: PasskeySession;
+}
+
+export interface PasskeyRegisterOptions {
+  challenge: string;
+  rp: {
+    name: string;
+    id: string;
+  };
+  user: {
+    id: string;
+    name: string;
+    displayName: string;
+  };
+  pubKeyCredParams: {
+    type: 'public-key';
+    alg: number;
+  }[];
+  timeout: number;
+  authenticatorSelection: {
+    userVerification: 'required' | 'preferred' | 'discouraged';
+    residentKey: 'required' | 'preferred' | 'discouraged';
+  };
+}
+
+export interface PasskeyRegisterChallenge {
+  options: PasskeyRegisterOptions;
+  session: PasskeySession;
+}
+
+export interface PasskeyCredential {
+  id: string;
+  rawId: string;
+  response: {
+    clientDataJSON: string;
+    authenticatorData?: string;
+    signature?: string;
+    attestationObject?: string;
+  };
+  type: 'public-key';
+}
+
+export interface PasskeyStatus {
+  has_passkey: boolean;
+  registered_at?: number;
+  last_used_at?: number;
+}
+
+export interface IdentitySessionResponse {
+  access_token: string;
+  refresh_token: string;
+  token_type?: 'Bearer';
+  expires_in?: number;
+  user: SparkVaultUser | null;
+  account: SparkVaultAccount | null;
+}
+
+export interface Vault {
+  vault_id: string;
+  name: string;
+  description?: string;
+  status: 'sealed' | 'unsealed';
+  ingot_count: number;
+  storage_bytes: number;
+  created_at: number;
+  created_by_user_id?: string;
+  last_unsealed_at?: number;
+  unseal_count?: number;
+}
+
+export interface CreateVaultRequest {
+  name: string;
+  description?: string;
+}
+
+export interface CreateVaultResponse {
+  vault_id: string;
+  name: string;
+  description?: string;
+  vmk: string;
+  vmk_warning: string;
+  status: 'sealed';
+  created_at: number;
+}
+
+export interface UpdateVaultRequest {
+  name?: string;
+  description?: string;
+}
+
+export interface UpdateVaultResponse {
+  vault_id: string;
+  name: string;
+  description?: string;
+  updated_at: number;
+}
+
+export interface UnsealVaultRequest {
+  vmk: string;
+  ttl_seconds?: number;
+}
+
+export interface UnsealVaultResponse {
+  vat: string;
+  vault_id: string;
+  issued_at: number;
+  expires_at: number;
+  ttl_seconds: number;
+}
+
+export interface ListVaultsResponse {
+  vaults: Vault[];
+  total: number;
+}
+
+export interface Ingot {
+  ingot_id: string;
+  name: string;
+  content_type: string;
+  size_bytes: number;
+  storage_location: 'dynamodb' | 's3';
+  status?: 'uploading' | 'encrypting' | 'active' | 'failed';
+  folder_id?: string | null;
+  created_at: number;
+  accessed_at?: number;
+  access_count?: number;
+  expires_at?: number;
+}
+
+export interface ListIngotsResponse {
+  ingots: Ingot[];
+  total: number;
+  next_cursor?: string;
+}
+
+export interface UploadResult {
+  ingot_id: string;
+  name: string;
+  size_bytes: number;
+  storage_location: 's3';
+}
+
+export interface IngotSharingConfig {
+  shared: boolean;
+  visibility?: 'invite_only' | 'authenticated' | 'public';
+  share_code?: string;
+  share_url?: string;
+  invites?: IngotInvite[];
+}
+
+export interface IngotInvite {
+  invite_id: string;
+  identity: string;
+  identity_type: 'email';
+  created_at: number;
+}
+
+export interface IngotAccessLog {
+  log_id: string;
+  action: 'download' | 'view';
+  identity: string;
+  ip_address: string;
+  user_agent: string;
+  timestamp: number;
+}
+
+export interface IngotAccessStats {
+  total_downloads: number;
+  unique_visitors: number;
+  last_accessed_at?: number;
+}
+
+export interface Folder {
+  folder_id: string;
+  vault_id: string;
+  name: string;
+  parent_id: string | null;
+  is_system: boolean;
+  pinned: boolean;
+  created_at: number;
+  updated_at?: number;
+  path?: string;
+  depth?: number;
+  ingot_count?: number;
+}
+
+export interface CreateFolderRequest {
+  name: string;
+  parent_id?: string | null;
+}
+
+export interface UpdateFolderRequest {
+  name?: string;
+  parent_id?: string | null;
+  pinned?: boolean;
+}
+
+export interface ListFoldersResponse {
+  folders: Folder[];
+  total: number;
+}
+
+export interface FolderBreadcrumbItem {
+  folder_id: string | null;
+  name: string;
+}
+
+export interface TokenStorageAdapter {
+  getAccessToken(): Promise<string | null>;
+  setAccessToken(token: string): Promise<void>;
+  getRefreshToken(): Promise<string | null>;
+  setRefreshToken(token: string): Promise<void>;
+  setTokens?(accessToken: string, refreshToken: string): Promise<void>;
+  clearTokens(): Promise<void>;
+  getUser?<T = SparkVaultUser>(): Promise<T | null>;
+  setUser?<T = SparkVaultUser>(user: T): Promise<void>;
+  getAccount?<T = SparkVaultAccount>(): Promise<T | null>;
+  setAccount?<T = SparkVaultAccount>(account: T): Promise<void>;
+  clearAll?(): Promise<void>;
+}
+
+export type FetchLike = (
+  url: string,
+  options?: RequestInit & {
+    timeoutMs?: number;
+    responseType?: XMLHttpRequestResponseType;
+  }
+) => Promise<Response>;
+
+export interface SparkVaultLogger {
+  debug(message: string, context?: Record<string, unknown>): void;
+  info(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  error(message: string, context?: Record<string, unknown>): void;
+}
+
+export interface MobileFileReader {
+  readAsBase64(fileUri: string, options: { position: number; length: number }): Promise<string>;
+}
+
+export interface MobileDownloadProgress {
+  bytesWritten: number;
+  bytesTotal?: number;
+}
+
+export interface MobileDownloadedFile {
+  uri: string;
+  status?: number;
+  headers?: Record<string, string>;
+  sizeBytes?: number;
+}
+
+export interface MobileFileInfo {
+  exists: boolean;
+  sizeBytes?: number;
+}
+
+export interface MobileFileDownloader {
+  download(
+    url: string,
+    fileUri: string,
+    options?: {
+      timeoutMs?: number;
+      abortSignal?: AbortSignal;
+      onProgress?: (progress: MobileDownloadProgress) => void;
+    }
+  ): Promise<MobileDownloadedFile | null>;
+  getInfo(fileUri: string): Promise<MobileFileInfo>;
+  delete(fileUri: string): Promise<void>;
+}
+
+export interface DebugLogger {
+  log(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  success(message: string): void;
+}
+
+export interface UploadProgressCallback {
+  (bytesUploaded: number, bytesTotal: number): void;
+}

package/src/validation.ts

@@ -0,0 +1,49 @@
+import { SparkVaultValidationError } from './errors.js';
+
+export function isSafeId(id: string): boolean {
+  if (!id || typeof id !== 'string') return false;
+  if (id.includes('/') || id.includes('\\') || id.includes('..') || id.includes('\0')) return false;
+  if (id.length < 8 || id.length > 128) return false;
+  return /^[a-zA-Z0-9_-]+$/.test(id);
+}
+
+export function validateVaultId(vaultId: string): void {
+  if (!isSafeId(vaultId)) {
+    throw new SparkVaultValidationError('Invalid vault ID format', { vaultId });
+  }
+}
+
+export function validateIngotId(ingotId: string): void {
+  if (!isSafeId(ingotId)) {
+    throw new SparkVaultValidationError('Invalid ingot ID format', { ingotId });
+  }
+}
+
+export function validateFolderId(folderId: string): void {
+  if (!folderId || typeof folderId !== 'string' || !folderId.startsWith('fld_') || !isSafeId(folderId)) {
+    throw new SparkVaultValidationError('Invalid folder ID format', { folderId });
+  }
+}
+
+export function sanitizeFilename(filename: string): string {
+  const reservedNames = new Set([
+    'CON', 'PRN', 'AUX', 'NUL',
+    'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
+    'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9',
+  ]);
+
+  let sanitized = filename
+    .replace(/\0/g, '')
+    .replace(/[\x00-\x1f\x7f]/g, '')
+    .replace(/\.\./g, '')
+    .replace(/[\/\\]/g, '_')
+    .replace(/^\.+/, '')
+    .trim();
+
+  const baseName = sanitized.split('.')[0].toUpperCase();
+  if (reservedNames.has(baseName)) {
+    sanitized = `_${sanitized}`;
+  }
+
+  return sanitized || 'file';
+}