@sparkvault/sdk-mobile 6.0.2 → 7.0.0

package/src/notify.ts

@@ -1,4 +1,6 @@
 import type { MobileHttpClient } from './http.js';
+import { apiPath } from './request-path.js';
+import { validateResourceId } from './validation.js';
 
 /** Inbox views the feed can be filtered to. `all` excludes archived rows. */
 export type NotificationInboxState = 'all' | 'unseen' | 'unread' | 'archived';
@@ -34,10 +36,15 @@ export interface NotificationRow {
    * The grant to open. Present only while a live reveal stands behind it — a
    * SEALED (secure) send that has not been recalled. A cleartext send delivers its
    * content inline in the channel and mints no grant; a recalled row's grant is
-   * revoked and the pointer is withheld rather than echoed. Guard before building
-   * a URL from it.
+   * revoked and the pointer is withheld rather than echoed.
    */
   sparklink_code?: string;
+  /**
+   * Where the grant opens: the URL every Notify channel carries for it, built by
+   * the server. Present exactly when `sparklink_code` is; open this rather than
+   * building a URL from the code.
+   */
+  pointer_url?: string;
   /**
    * True only when there is a secure part left to reveal — exactly when
    * `sparklink_code` is present. `false` does NOT mean "cleartext row": a recalled
@@ -150,21 +157,15 @@ export class MobileNotifyClient {
 
   /** The caller's own inbox feed (newest first). */
   async getInbox(options: ListNotificationsOptions = {}): Promise<ListNotificationsResponse> {
-    const params = new URLSearchParams();
-    if (options.state) params.set('state', options.state);
-    if (options.limit) params.set('limit', String(options.limit));
-    if (options.cursor) params.set('cursor', options.cursor);
-
-    const query = params.toString();
-    const response = await this.http.get<ListNotificationsResponse>(
-      query ? `/me/notifications?${query}` : '/me/notifications'
-    );
+    const response = await this.http.get<ListNotificationsResponse>(apiPath`/me/notifications`, {
+      query: { state: options.state, limit: options.limit || undefined, cursor: options.cursor },
+    });
     return response.data;
   }
 
   /** Bounded unseen badge count for the caller's own inbox. */
   async getUnreadCount(): Promise<UnreadCountResponse> {
-    const response = await this.http.get<UnreadCountResponse>('/me/notifications/unread-count');
+    const response = await this.http.get<UnreadCountResponse>(apiPath`/me/notifications/unread-count`);
     return response.data;
   }
 
@@ -176,8 +177,9 @@ export class MobileNotifyClient {
     notificationId: string,
     options: MarkNotificationStateOptions
   ): Promise<MarkNotificationStateResponse> {
+    validateResourceId(notificationId, 'notification ID', 'notificationId');
     const response = await this.http.post<MarkNotificationStateResponse>(
-      `/me/notifications/${encodeURIComponent(notificationId)}/state`,
+      apiPath`/me/notifications/${notificationId}/state`,
       { created_at: options.createdAt, state: options.state }
     );
     return response.data;
@@ -198,7 +200,7 @@ export class MobileNotifyClient {
     if (options.cursor) body.cursor = options.cursor;
 
     const response = await this.http.post<MarkAllNotificationsStateResponse>(
-      '/me/notifications/state',
+      apiPath`/me/notifications/state`,
       body
     );
     return response.data;
@@ -232,7 +234,7 @@ export class MobileNotifyClient {
 
   /** Register/refresh this device's Expo push token under the session user. */
   async registerDevice(pushToken: string): Promise<RegisterDeviceResponse> {
-    const response = await this.http.post<RegisterDeviceResponse>('/me/notifications/devices', {
+    const response = await this.http.post<RegisterDeviceResponse>(apiPath`/me/notifications/devices`, {
       push_token: pushToken,
     });
     return response.data;
@@ -244,7 +246,7 @@ export class MobileNotifyClient {
    * itself, so the caller never reimplements that derivation.
    */
   async unregisterDeviceToken(pushToken: string): Promise<void> {
-    await this.http.delete('/me/notifications/devices', { body: { token: pushToken } });
+    await this.http.delete(apiPath`/me/notifications/devices`, { body: { token: pushToken } });
   }
 
   /**
@@ -252,6 +254,6 @@ export class MobileNotifyClient {
    * Use `unregisterDeviceToken` when the caller holds the token itself.
    */
   async unregisterDevice(tokenHash: string): Promise<void> {
-    await this.http.delete(`/me/notifications/devices/${encodeURIComponent(tokenHash)}`);
+    await this.http.delete(apiPath`/me/notifications/devices/${tokenHash}`);
   }
 }

package/src/products/identity.ts

@@ -1,6 +1,8 @@
 import { identityUrl, type ResolvedMobileConfig } from '../config.js';
 import { base64UrlToBytes, base64UrlToUtf8, utf8ToBytes } from '../encoding.js';
 import { SparkVaultAuthenticationError, SparkVaultMobileError, SparkVaultValidationError } from '../errors.js';
+import { inferIdentityType, normalizeIdentifier } from '../identity-input.js';
+import { apiPath, type ApiPath } from '../request-path.js';
 import type {
   ApiErrorBody,
   BackupSendResponse,
@@ -105,7 +107,7 @@ export class MobileIdentityClient {
   }
 
   getJwksUri(): string {
-    return identityUrl(this.config, '/.well-known/jwks.json');
+    return identityUrl(this.config, apiPath`/.well-known/jwks.json`);
   }
 
   async getConfig(): Promise<IdentityConfig> {
@@ -133,7 +135,7 @@ export class MobileIdentityClient {
     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.jwksCache = this.getIdentity<IdentityJwks>(apiPath`/.well-known/jwks.json`);
       this.jwksCachedAt = now;
     }
 
@@ -158,25 +160,18 @@ export class MobileIdentityClient {
       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;
-
+    const claims = this.decodeIdentityTokenClaims(token);
+    const [headerPart, payloadPart, signaturePart] = token.split('.');
+    let parsedHeader: unknown = null;
     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;
+      parsedHeader = JSON.parse(base64UrlToUtf8(headerPart));
     } catch {
+      // Refused below with every other unusable header.
+    }
+    if (typeof parsedHeader !== 'object' || parsedHeader === null || Array.isArray(parsedHeader)) {
       throw new SparkVaultValidationError('Invalid identity token payload');
     }
+    const header = parsedHeader as JwtHeader;
 
     if (header.alg !== 'EdDSA') {
       throw new SparkVaultValidationError('Unsupported identity token algorithm', { alg: header.alg });
@@ -258,7 +253,7 @@ export class MobileIdentityClient {
       kindling: string;
       expires_at?: number;
       retry_after?: number;
-    }>('/otp/send', {
+    }>(apiPath`/otp/send`, {
       recipient: identity,
       method: request.method,
     });
@@ -331,7 +326,7 @@ export class MobileIdentityClient {
    * identity result. A wrong code throws.
    */
   async submitSecondFactor(request: SubmitSecondFactorRequest): Promise<IdentityVerifyResult> {
-    const result = await this.postIdentity<IdentityVerificationResponse>('/second-factor/verify', {
+    const result = await this.postIdentity<IdentityVerificationResponse>(apiPath`/second-factor/verify`, {
       ticket: request.ticket,
       code: request.code,
     });
@@ -367,7 +362,7 @@ export class MobileIdentityClient {
   async checkPasskeyStatus(identity: string, identityType?: IdentityType): Promise<{ hasPasskey: boolean }> {
     try {
       const result = await this.postIdentity<{ has_passkey: boolean }>(
-        '/passkey/check',
+        apiPath`/passkey/check`,
         this.identityLookupBody(identity, identityType)
       );
       return { hasPasskey: Boolean(result.has_passkey) };
@@ -377,7 +372,7 @@ export class MobileIdentityClient {
   }
 
   async getPasskeyAuthOptions(_identity?: string, _identityType?: IdentityType): Promise<PasskeyAuthChallenge> {
-    return this.postIdentity<PasskeyAuthChallenge>('/passkey/verify', {});
+    return this.postIdentity<PasskeyAuthChallenge>(apiPath`/passkey/verify`, {});
   }
 
   async completePasskeyAuthentication(
@@ -385,7 +380,7 @@ export class MobileIdentityClient {
     session: PasskeySession
   ): Promise<IdentityVerifyResult> {
     const result = await this.postIdentity<IdentityPasskeyCompletionResponse>(
-      '/passkey/verify/complete',
+      apiPath`/passkey/verify/complete`,
       { session, credential }
     );
 
@@ -422,7 +417,7 @@ export class MobileIdentityClient {
     const normalized = this.normalizeIdentity(identity, identityType);
     const identityBody = identityType === 'phone' ? { phone: normalized } : { email: normalized };
 
-    return this.postIdentity<PasskeyRegisterChallenge>('/passkey/register', {
+    return this.postIdentity<PasskeyRegisterChallenge>(apiPath`/passkey/register`, {
       ...identityBody,
       registration_token: params.registrationToken,
       device_name: params.deviceName ?? this.config.userAgent,
@@ -434,7 +429,7 @@ export class MobileIdentityClient {
     session: PasskeySession
   ): Promise<{ success: boolean; credential_id: string }> {
     const result = await this.postIdentity<IdentityPasskeyCompletionResponse>(
-      '/passkey/register/complete',
+      apiPath`/passkey/register/complete`,
       { session, credential }
     );
 
@@ -464,7 +459,7 @@ export class MobileIdentityClient {
    * Authorized by the login's verification token. Best-effort.
    */
   async dismissRecommendation(params: { verificationToken: string; key: RecommendationKey }): Promise<void> {
-    await this.postIdentity('/recommendations/dismiss', {
+    await this.postIdentity(apiPath`/recommendations/dismiss`, {
       verification_token: params.verificationToken,
       key: params.key
     });
@@ -482,10 +477,10 @@ export class MobileIdentityClient {
     value: string;
     method?: 'email' | 'sms' | 'voice';
   }): Promise<BackupSendResponse> {
-    return this.postIdentity<BackupSendResponse>('/backup-verification/send', {
+    return this.postIdentity<BackupSendResponse>(apiPath`/backup-verification/send`, {
       verification_token: params.verificationToken,
       type: params.type,
-      value: params.value,
+      value: this.normalizeIdentity(params.value, params.type),
       ...(params.method ? { method: params.method } : {}),
     });
   }
@@ -498,7 +493,7 @@ export class MobileIdentityClient {
     sessionId: string;
     code: string;
   }): Promise<BackupVerifyResponse> {
-    return this.postIdentity<BackupVerifyResponse>('/backup-verification/verify', {
+    return this.postIdentity<BackupVerifyResponse>(apiPath`/backup-verification/verify`, {
       session_id: params.sessionId,
       code: params.code,
     });
@@ -506,10 +501,10 @@ export class MobileIdentityClient {
 
   private async verifyOtpWithRetryErrors(request: VerifyOtpRequest): Promise<IdentityVerificationResponse> {
     try {
-      return await this.postIdentity<IdentityVerificationResponse>('/otp/verify', {
+      return await this.postIdentity<IdentityVerificationResponse>(apiPath`/otp/verify`, {
         kindling: request.kindling,
         pin: request.pin,
-        recipient: request.recipient.trim().toLowerCase(),
+        recipient: this.normalizeIdentity(request.recipient, inferIdentityType(request.recipient)),
       });
     } catch (err) {
       const apiError = err as SparkVaultMobileError & {
@@ -535,7 +530,7 @@ export class MobileIdentityClient {
   }
 
   private startConfigLoad(): Promise<IdentityConfig> {
-    const request = this.getIdentity<IdentityConfig>('/config').catch((error: unknown) => {
+    const request = this.getIdentity<IdentityConfig>(apiPath`/config`).catch((error: unknown) => {
       this.configCache = null;
       throw error;
     });
@@ -582,7 +577,7 @@ export class MobileIdentityClient {
     }
   }
 
-  private async getIdentity<T>(path: string): Promise<T> {
+  private async getIdentity<T>(path: ApiPath): Promise<T> {
     const response = await this.config.fetch(identityUrl(this.config, path), {
       method: 'GET',
       headers: this.identityHeaders(),
@@ -605,7 +600,7 @@ export class MobileIdentityClient {
   }
 
   private async postIdentity<T>(
-    path: string,
+    path: ApiPath,
     body: Record<string, unknown>,
     options: { bearerToken?: string } = {}
   ): Promise<T> {
@@ -647,17 +642,28 @@ export class MobileIdentityClient {
   }
 
   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 };
+    const type = identityType ?? inferIdentityType(identity);
+    const normalized = this.normalizeIdentity(identity, type);
+    return type === 'phone' ? { phone: normalized } : { email: normalized };
   }
 
+  /**
+   * An identity as the Identity Product keys it, read as the given type: the
+   * sign-in dialog's rule, so a number or address resolves to the same identity
+   * through every method.
+   */
   private normalizeIdentity(identity: string, identityType: IdentityType): string {
-    const trimmed = identity.trim();
-    if (!trimmed) {
+    if (!identity.trim()) {
       throw new SparkVaultValidationError('Identity is required', { field: 'identity' });
     }
-    return identityType === 'email' ? trimmed.toLowerCase() : trimmed;
+    const normalized = normalizeIdentifier(identity, identityType);
+    if (normalized === null) {
+      throw new SparkVaultValidationError(
+        identityType === 'phone' ? 'Invalid phone number' : 'Invalid email address',
+        { field: 'identity' }
+      );
+    }
+    return normalized;
   }
 
   private selectJwk(jwks: IdentityJwks, kid?: string): { x: string } {

package/src/request-path.ts

@@ -0,0 +1,45 @@
+/**
+ * Request paths: the one way a module names a SparkVault route.
+ *
+ * Every request the SDK sends carries the caller's credentials (the session's
+ * Bearer token, plus a Vault Access Token on vault data), so a value that
+ * smuggled '/' or a dot-segment into a path would re-target that credentialed
+ * request at another route. `apiPath` closes that by construction: each
+ * interpolated value becomes exactly one percent-encoded segment, and a value
+ * that cannot be one segment is refused before any request leaves. The
+ * transport accepts only an `ApiPath`, so no module can name a route any other
+ * way.
+ *
+ * The rules are the platform's one copy, mirrored from
+ * `@sparkvault/app-sdk/request-path` into `./app-sdk/request-path.js`; this
+ * module only types them and raises this SDK's error.
+ */
+
+import { buildRequestPath, encodePathSegment, queryString } from './app-sdk/request-path.js';
+import { SparkVaultValidationError } from './errors.js';
+
+declare const API_PATH: unique symbol;
+
+/** A route path whose every interpolated value is exactly one encoded segment. */
+export type ApiPath = string & { readonly [API_PATH]: true };
+
+/** Query parameters; `undefined`, `null` and `''` are left out of the query. */
+export type QueryParams = Record<string, string | number | boolean | null | undefined>;
+
+/**
+ * Build a route path from a template: `apiPath\`/vaults/${vaultId}\``.
+ *
+ * @throws SparkVaultValidationError when an interpolated value cannot be
+ *   exactly one path segment ('', '.', '..', a non-string, or malformed UTF-16).
+ */
+export function apiPath(literals: TemplateStringsArray, ...values: string[]): ApiPath {
+  const path = buildRequestPath(literals, values);
+  if (path === null) {
+    throw new SparkVaultValidationError('A path value must be exactly one path segment', {
+      received: values.find(value => encodePathSegment(value) === null),
+    });
+  }
+  return path as ApiPath;
+}
+
+export { queryString };

package/src/sparks.ts

@@ -1,5 +1,7 @@
 import type { MobileHttpClient } from './http.js';
 import type { ShareSparkResponse, SparkShareStatus, UnshareSparkResponse } from './types.js';
+import { apiPath } from './request-path.js';
+import { validateResourceId } from './validation.js';
 
 export interface Spark {
   spark_id: string;
@@ -55,23 +57,20 @@ export class MobileSparksClient {
   }
 
   async list(options: ListSparksOptions = {}): Promise<ListSparksResponse> {
-    const params = new URLSearchParams();
-    if (options.kindling) params.set('kindling', options.kindling);
-    if (options.limit) params.set('limit', String(options.limit));
-    if (options.cursor) params.set('cursor', options.cursor);
-
-    const query = params.toString();
-    const response = await this.http.get<ListSparksResponse>(query ? `/sparks?${query}` : '/sparks');
+    const response = await this.http.get<ListSparksResponse>(apiPath`/sparks`, {
+      query: { kindling: options.kindling, limit: options.limit || undefined, cursor: options.cursor },
+    });
     return response.data;
   }
 
   async get(sparkId: string): Promise<SparkResponse> {
-    const response = await this.http.get<SparkResponse>(`/sparks/${encodeURIComponent(sparkId)}`);
+    validateResourceId(sparkId, 'spark ID', 'sparkId');
+    const response = await this.http.get<SparkResponse>(apiPath`/sparks/${sparkId}`);
     return response.data;
   }
 
   async create(options: CreateSparkOptions): Promise<CreateSparkResponse> {
-    const response = await this.http.post<CreateSparkResponse>('/sparks', {
+    const response = await this.http.post<CreateSparkResponse>(apiPath`/sparks`, {
       payload: options.payload,
       content_type: options.contentType,
       ttl_minutes: options.ttlMinutes,
@@ -83,7 +82,8 @@ export class MobileSparksClient {
 
   /** Burn a spark before its natural expiry. An already-burned spark resolves (the server returns 204); a missing spark rejects with a 404. */
   async delete(sparkId: string): Promise<void> {
-    await this.http.delete(`/sparks/${encodeURIComponent(sparkId)}`);
+    validateResourceId(sparkId, 'spark ID', 'sparkId');
+    await this.http.delete(apiPath`/sparks/${sparkId}`);
   }
 
   /**
@@ -92,13 +92,14 @@ export class MobileSparksClient {
    * shared.
    */
   async share(sparkId: string, options: ShareSparkOptions = {}): Promise<ShareSparkResponse> {
+    validateResourceId(sparkId, 'spark ID', 'sparkId');
     const body: Record<string, unknown> = {};
     if (options.visibility) body.visibility = options.visibility;
     if (options.invites) body.invites = options.invites;
     if (options.expiresInSeconds !== undefined) body.expires_in_seconds = options.expiresInSeconds;
 
     const response = await this.http.patch<ShareSparkResponse>(
-      `/sparks/${encodeURIComponent(sparkId)}/share`,
+      apiPath`/sparks/${sparkId}/share`,
       body
     );
     return response.data;
@@ -106,16 +107,18 @@ export class MobileSparksClient {
 
   /** Current sharing status for a spark. `shared` is false when no SparkLink exists. */
   async getShare(sparkId: string): Promise<SparkShareStatus> {
+    validateResourceId(sparkId, 'spark ID', 'sparkId');
     const response = await this.http.get<SparkShareStatus>(
-      `/sparks/${encodeURIComponent(sparkId)}/share`
+      apiPath`/sparks/${sparkId}/share`
     );
     return response.data;
   }
 
   /** Revoke a spark's SparkLink. Resolves whether or not a link existed. */
   async unshare(sparkId: string): Promise<UnshareSparkResponse> {
+    validateResourceId(sparkId, 'spark ID', 'sparkId');
     const response = await this.http.delete<UnshareSparkResponse>(
-      `/sparks/${encodeURIComponent(sparkId)}/share`
+      apiPath`/sparks/${sparkId}/share`
     );
     return response.data;
   }