@signalwire/js 4.0.0-dev-20260326210326 → 4.0.0-dev-20260401154549

package/dist/index.d.cts

@@ -175,6 +175,26 @@ interface Storage {
   getItem(key: string, scope: StorageScope): Promise<string | null>;
   removeItem(key: string, scope: StorageScope): Promise<void>;
 }
+/**
+ * Context provided by the SDK when calling {@link CredentialProvider.authenticate}.
+ *
+ * Contains optional parameters the SDK generates internally (e.g., DPoP fingerprint)
+ * that the implementor can forward to their server-side token endpoint.
+ */
+interface AuthenticateContext {
+  /**
+   * JWK Thumbprint (RFC 7638) of the SDK's ephemeral DPoP key pair.
+   *
+   * When present, the implementor should forward this value as the `fingerprint`
+   * parameter to the server-side SAT issuance endpoint alongside `scope: "sat:refresh"`.
+   * This enables the server to bind the SAT to the SDK's key pair, allowing
+   * automatic Client Bound SAT refresh without developer intervention.
+   *
+   * When absent (e.g., Web Crypto API not available), the implementor should
+   * proceed without DPoP binding.
+   */
+  fingerprint?: string;
+}
 /**
  * Provides authentication credentials to the SDK.
  *
@@ -194,12 +214,14 @@ interface CredentialProvider {
    * Implementor responsibilities:
    * - Resolve with a valid {@link SDKCredential} on success.
    * - Reject (throw) on failure — this will cause client initialization to fail.
+   * - When `context.fingerprint` is provided, forward it to the server-side token
+   *   endpoint with `scope: "sat:refresh"` to enable automatic token refresh.
    *
    * SDK behavior:
    * - Awaits this method before establishing the WebSocket connection.
    * - On rejection, propagates the error to the caller of `SignalWire()`.
    */
-  authenticate(): Promise<SDKCredential>;
+  authenticate(context?: AuthenticateContext): Promise<SDKCredential>;
   /**
    * Obtains fresh credentials before the current ones expire. Optional.
    *
@@ -212,7 +234,10 @@ interface CredentialProvider {
    * - Scheduled automatically before expiry; implementors do not need to manage timing.
    * - On rejection, the refresh schedule stops and the session continues with the
    *   current credentials until they expire.
-   * - When not provided, the SDK uses the initial credentials for the entire session lifetime.
+   * - When not provided and the SAT includes a `sat:refresh` scope, the SDK
+   *   automatically refreshes via Client Bound SAT (DPoP) without developer intervention.
+   * - When not provided and no refresh scope is present, the SDK uses the initial
+   *   credentials for the entire session lifetime.
    */
   refresh?: () => Promise<SDKCredential>;
 }
@@ -389,11 +414,13 @@ interface HTTPRequestControllerOptions {
 }
 declare class HTTPRequestController {
   private baseURL;
-  private credential;
+  private readonly getCredential;
   private static readonly defaultMaxRetries;
   private static readonly defaultRetryDelayMinMs;
   private static readonly defaultRetryDelayMaxMs;
   private static readonly defaultRequestTimeoutMs;
+  /** Sensitive field names to mask in debug logs. */
+  private static readonly SENSITIVE_BODY_FIELDS;
   private readonly maxRetries;
   private readonly retryDelayMin;
   private readonly retryDelayMax;
@@ -401,7 +428,7 @@ declare class HTTPRequestController {
   private _responses$;
   private _errors$;
   private _status$;
-  constructor(baseURL: string, credential: SDKCredential, options?: HTTPRequestControllerOptions);
+  constructor(baseURL: string, getCredential: () => SDKCredential, options?: HTTPRequestControllerOptions);
   get status$(): Observable<HTTPRequestStatus>;
   get status(): HTTPRequestStatus;
   get responses$(): Observable<HTTPResponse>;
@@ -411,6 +438,10 @@ declare class HTTPRequestController {
   private executeRequest;
   private buildURL;
   private buildHeaders;
+  /**
+   * Sanitizes a request body for debug logging by masking sensitive fields.
+   */
+  private sanitizeBody;
   private convertResponse;
 }
 //#endregion
@@ -460,6 +491,33 @@ interface GetAddressResponse {
   created_at: string;
 }
 //#endregion
+//#region src/core/types/crypto.types.d.ts
+/** Parameters for creating an HTTP DPoP proof (for Prime API endpoints). */
+interface DPoPHttpProofParams {
+  /** HTTP method (e.g., "POST"). */
+  readonly method: string;
+  /** Request URI — should be the full URL per RFC 9449 (e.g., "https://fabric.signalwire.com/api/..."). */
+  readonly uri: string;
+  /** Access token to bind via `ath` claim (SHA-256 hash). Used for resource endpoints, not token endpoints. */
+  readonly accessToken?: string;
+}
+/** Parameters for creating an RPC DPoP proof (for switchblade WebSocket methods). */
+interface DPoPRpcProofParams {
+  /** RPC method name (e.g., "signalwire.connect" or "signalwire.reauthenticate"). */
+  readonly method: string;
+}
+/** SAT claims returned by /api/fabric/subscriber/info. */
+interface SATClaims {
+  /** Token scopes (e.g., ["sat:refresh"]). */
+  scope?: string[];
+  /** Confirmation claim binding the token to a key. */
+  cnf?: {
+    jkt: string;
+  };
+  /** Token expiry timestamp in seconds since epoch. */
+  expires_at?: number;
+}
+//#endregion
 //#region src/core/types/subscriber.types.d.ts
 /** Raw subscriber profile response from the SignalWire Fabric API. */
 interface GetSubscriberInfoResponse {
@@ -494,6 +552,8 @@ interface GetSubscriberInfoResponse {
   };
   /** Fabric addresses associated with this subscriber. */
   fabric_addresses: GetAddressResponse[];
+  /** Filtered SAT claims (scope, cnf, expires_at) returned when the token has special capabilities. */
+  sat_claims?: SATClaims;
 }
 //#endregion
 //#region src/core/entities/Subscriber.d.ts
@@ -533,6 +593,8 @@ declare class Subscriber extends Fetchable<GetSubscriberInfoResponse> {
   };
   /** Fabric addresses associated with this subscriber. */
   addresses: GetAddressResponse[];
+  /** Filtered SAT claims when the token has special capabilities (e.g., refresh scope). */
+  satClaims?: SATClaims;
   constructor(http: HTTPRequestController);
   protected populateInstance(data: GetSubscriberInfoResponse): void;
 }
@@ -744,6 +806,11 @@ interface CallUpdatedPayload {
   room_id: string;
   room_session_id: string;
 }
+interface RoomUpdatedPayload {
+  room_session: RoomSession;
+  room_id: string;
+  room_session_id: string;
+}
 interface CallStatePayload {
   call_id: string;
   node_id: string;
@@ -931,19 +998,36 @@ declare class MediaTrackError extends Error {
   originalError: unknown;
   constructor(operation: string, kind: string, originalError: unknown);
 }
+declare class DPoPInitError extends Error {
+  originalError: unknown;
+  constructor(originalError: unknown, message?: string);
+}
+declare class DeviceTokenError extends Error {
+  originalError?: unknown | undefined;
+  constructor(message: string, originalError?: unknown | undefined);
+}
+declare class TokenRefreshError extends Error {
+  originalError?: unknown | undefined;
+  constructor(message: string, originalError?: unknown | undefined);
+}
 //#endregion
 //#region src/core/RPCMessages/RPCConnect.d.ts
 interface Authorization {
   jti: string;
   project_id: string;
+  data_zone?: string;
+  scope?: string[];
   fabric_subscriber: {
     version: number;
     expires_at: number;
     subscriber_id: string;
-    application_id: string;
+    application_id: string | null;
     project_id: string;
     space_id: string;
   };
+  cnf?: {
+    jkt: string;
+  };
 }
 //#endregion
 //#region src/core/utils.d.ts
@@ -1962,6 +2046,90 @@ declare class TransportManager extends Destroyable {
   private _init;
 }
 //#endregion
+//#region src/controllers/CryptoController.d.ts
+/**
+ * Controls DPoP (Demonstrating Proof-of-Possession) cryptographic operations.
+ *
+ * Generates an ephemeral RSA-2048 key pair where the private key is
+ * non-extractable, computes the JWK Thumbprint (RFC 7638) as the fingerprint,
+ * and creates signed DPoP proof JWTs for both HTTP API requests and
+ * WebSocket RPC calls.
+ *
+ * @example
+ * ```typescript
+ * const crypto = new CryptoController();
+ * await crypto.init();
+ *
+ * // Get fingerprint for SAT issuance
+ * const fingerprint = crypto.fingerprint;
+ *
+ * // Create proof for HTTP endpoint
+ * const httpProof = await crypto.createHttpProof({
+ *   method: 'POST',
+ *   uri: '/api/fabric/subscriber/devices/token'
+ * });
+ *
+ * // Create proof for RPC call
+ * const rpcProof = await crypto.createRpcProof({
+ *   method: 'signalwire.connect'
+ * });
+ * ```
+ */
+declare class CryptoController {
+  private _keyPair;
+  private _publicJwk;
+  private _fingerprint;
+  private _initialized;
+  /**
+   * Generates the ephemeral RSA key pair and computes the fingerprint.
+   *
+   * Must be called before any other method. The private key is generated
+   * as non-extractable to prevent accidental exposure.
+   *
+   * @returns The JWK Thumbprint (fingerprint) for the generated key.
+   */
+  init(): Promise<string>;
+  /**
+   * The JWK Thumbprint (RFC 7638) of the public key.
+   * Used as the `fingerprint` parameter when requesting scoped SATs.
+   *
+   * @throws {DPoPInitError} If {@link init} has not been called.
+   */
+  get fingerprint(): string;
+  /**
+   * Whether the controller has been initialized with a key pair.
+   */
+  get initialized(): boolean;
+  /**
+   * Creates a DPoP proof JWT for an HTTP API request.
+   *
+   * Used for Prime API endpoints like `/api/fabric/subscriber/devices/token`
+   * and `/api/fabric/subscriber/devices/refresh`.
+   *
+   * @param params - HTTP method and URI for the proof.
+   * @returns Signed DPoP proof JWT string.
+   */
+  createHttpProof(params: DPoPHttpProofParams): Promise<string>;
+  /**
+   * Creates a DPoP proof JWT for a WebSocket RPC call.
+   *
+   * Used for switchblade RPC methods like `signalwire.connect` and
+   * `signalwire.reauthenticate`.
+   *
+   * @param params - RPC method name for the proof.
+   * @returns Signed DPoP proof JWT string.
+   */
+  createRpcProof(params: DPoPRpcProofParams): Promise<string>;
+  /**
+   * Releases the key pair references.
+   * After calling destroy, the controller must be re-initialized to be used again.
+   */
+  destroy(): void;
+  private get publicJwk();
+  private get privateKey();
+  private signProof;
+}
+//#endregion
 //#region src/core/entities/Directory.d.ts
 /**
  * Directory interface for managing addresses
@@ -2072,11 +2240,12 @@ interface SessionState extends ClientSession {
 //#endregion
 //#region src/managers/ClientSessionManager.d.ts
 declare class ClientSessionManager extends Destroyable implements SessionState {
-  private credential;
+  private readonly getCredential;
   private readonly transport;
   private readonly storage;
   private readonly authorizationStateKey;
   private readonly attachManager;
+  private readonly dpopManager?;
   private callFactory;
   private callCreateTimeout;
   private readonly agent;
@@ -2084,14 +2253,21 @@ declare class ClientSessionManager extends Destroyable implements SessionState {
   initialized$: Observable<boolean>;
   private authorizationState$;
   private connectVersion;
+  /**
+   * Optional hook called before a fresh connect on reconnect.
+   * Used by SignalWire to refresh expired credentials before re-authenticating.
+   * @internal
+   */
+  onBeforeReconnect?: () => Promise<void>;
   private _authorization$;
   private _errors$;
   private _directory?;
   private _authenticated$;
+  private _clientBound;
   private _subscriberInfo$;
   private _calls$;
   private _iceServers$;
-  constructor(credential: SDKCredential, transport: TransportManager, storage: StorageManager, authorizationStateKey: string, deviceController: DeviceController, attachManager: AttachManager, webRTCApiProvider: WebRTCApiProvider);
+  constructor(getCredential: () => SDKCredential, transport: TransportManager, storage: StorageManager, authorizationStateKey: string, deviceController: DeviceController, attachManager: AttachManager, webRTCApiProvider: WebRTCApiProvider, dpopManager?: CryptoController | undefined);
   get incomingCalls$(): Observable<Call[]>;
   get incomingCalls(): Call[];
   get subscriberInfo$(): Observable<Address | null>;
@@ -2104,6 +2280,13 @@ declare class ClientSessionManager extends Destroyable implements SessionState {
   get errors$(): Observable<Error>;
   get authenticated$(): Observable<boolean>;
   get authenticated(): boolean;
+  /**
+   * Whether this session is client-bound (using a Client Bound SAT).
+   * When client-bound, DPoP proof creation failures are treated as
+   * authentication errors rather than silently degraded.
+   * @internal
+   */
+  get clientBound(): boolean;
   /**
    * Set the directory instance
    * Called by SignalWire after directory is created
@@ -2192,6 +2375,16 @@ declare class ClientSessionManager extends Destroyable implements SessionState {
     params: CallConnectPayload;
   }, "event_channel"> & {
     event_channel: string;
+  }) | (Omit<{
+    event_type: "room.updated";
+    event_channel: EventChannel;
+    timestamp: number;
+    project_id?: string;
+    node_id?: string;
+    is_author?: boolean;
+    params: RoomUpdatedPayload;
+  }, "event_channel"> & {
+    event_channel: string;
   }) | Omit<{
     event_type: "member.updated";
     event_channel: EventChannel;
@@ -2266,7 +2459,9 @@ declare class ClientSessionManager extends Destroyable implements SessionState {
   private handleAuthenticationError;
   cleanupStoredConnectionParams(): Promise<void>;
   protected updateAuthState(authorization_state: string): Promise<void>;
-  reauthenticate(token: string): Promise<void>;
+  reauthenticate(token: string, dpopToken?: string, options?: {
+    clientBound?: boolean;
+  }): Promise<void>;
   private authenticate;
   disconnect(): Promise<void>;
   private createInboundCall;
@@ -2354,6 +2549,16 @@ declare class ClientSessionWrapper implements SessionState {
     params: CallConnectPayload;
   }, "event_channel"> & {
     event_channel: string;
+  }) | (Omit<{
+    event_type: "room.updated";
+    event_channel: EventChannel;
+    timestamp: number;
+    project_id?: string;
+    node_id?: string;
+    is_author?: boolean;
+    params: RoomUpdatedPayload;
+  }, "event_channel"> & {
+    event_channel: string;
   }) | Omit<{
     event_type: "member.updated";
     event_channel: EventChannel;
@@ -2476,6 +2681,9 @@ declare class SignalWire extends Destroyable implements DeviceController {
   private _errors$;
   private _options;
   private _refreshTimerId?;
+  private _dpopManager?;
+  private _deviceTokenManager?;
+  private _credentialProvider?;
   private _deps;
   /**
    * Creates a new SignalWire client and begins connecting.
@@ -2484,6 +2692,10 @@ declare class SignalWire extends Destroyable implements DeviceController {
    * @param options - Configuration options (connection, device monitoring, preferences).
    */
   constructor(credentialProvider: CredentialProvider, options?: SignalWireOptions);
+  /**
+   * Initializes DPoP if not already set up. Returns the fingerprint on success.
+   */
+  private initDPoP;
   private validateCredentials;
   private init;
   private handleAttachments;
@@ -2924,6 +3136,7 @@ interface WebRTCVerto extends VertoManager {
 //#endregion
 //#region src/managers/CallEventsManager.d.ts
 interface WebRTCCallEventManagerOptions {}
+/** @internal */
 declare class CallEventsManager extends Destroyable {
   protected webRtcCallSession: CallManager;
   protected options: WebRTCCallEventManagerOptions;
@@ -3200,7 +3413,7 @@ declare class WebRTCCall extends Destroyable implements CallManager {
   /** Observable of WebRTC-specific signaling messages. */
   get webrtcMessages$(): Observable<WebrtcMessagePayload>;
   /** Observable of call-level signaling events. */
-  get callEvent$(): Observable<WebrtcMessagePayload | CallJoinedPayload | CallLeftPayload | CallUpdatedPayload | CallStatePayload | CallPlayPayload | CallConnectPayload | MemberUpdatedPayload | MemberJoinedPayload | MemberLeftPayload | MemberTalkingPayload | LayoutChangedPayload | ConversationMessagePayload>;
+  get callEvent$(): Observable<WebrtcMessagePayload | CallJoinedPayload | CallLeftPayload | CallUpdatedPayload | CallStatePayload | CallPlayPayload | CallConnectPayload | RoomUpdatedPayload | MemberUpdatedPayload | MemberJoinedPayload | MemberLeftPayload | MemberTalkingPayload | LayoutChangedPayload | ConversationMessagePayload>;
   /** Observable of layout-changed signaling events. */
   get layoutEvent$(): Observable<LayoutChangedPayload>;
   /**
@@ -3292,5 +3505,5 @@ declare const version: string;
  */
 declare const ready: boolean;
 //#endregion
-export { Address, type AddressHistory, type Call, type CallAddress, type CallCapabilitiesState, CallCreateError, type CallError, type CallErrorKind, type CallOptions, type CallParticipant, type CallSelfParticipant, type CallState, type CallStatus, ClientPreferences, CollectionFetchError, type CredentialProvider, type DeviceController, type DialOptions, type Directory, type ExecuteMethod, InvalidCredentialsError, type JSONRPCErrorResponse, type JSONRPCRequest, type JSONRPCResponse, type JSONRPCSuccessResponse, type LayoutLayer, type MediaDirection, type MediaDirections, type MediaOptions, MediaTrackError, type MemberCapabilities, MessageParseError, type NodeSocketAdapter, type OnOffCapability, Participant, type PendingRPCOptions, type SDKCredential, SelfCapabilities, SelfParticipant, type SessionState, SignalWire, type SignalWireOptions, StaticCredentialProvider, type Storage, Subscriber, type TextMessage, type TransferOptions, UnexpectedError, VertoPongError, type VideoPosition, type WebRTCApiProvider, WebRTCCall, type WebRTCMediaDevices, type WebSocketAdapter, embeddableCall, isSelfParticipant, ready, version };
+export { Address, type AddressHistory, type AuthenticateContext, type Call, type CallAddress, type CallCapabilitiesState, CallCreateError, type CallError, type CallErrorKind, type CallOptions, type CallParticipant, type CallSelfParticipant, type CallState, type CallStatus, ClientPreferences, CollectionFetchError, type CredentialProvider, DPoPInitError, type DeviceController, DeviceTokenError, type DialOptions, type Directory, type ExecuteMethod, InvalidCredentialsError, type JSONRPCErrorResponse, type JSONRPCRequest, type JSONRPCResponse, type JSONRPCSuccessResponse, type LayoutLayer, type MediaDirection, type MediaDirections, type MediaOptions, MediaTrackError, type MemberCapabilities, MessageParseError, type NodeSocketAdapter, type OnOffCapability, Participant, type PendingRPCOptions, type SATClaims, type SDKCredential, SelfCapabilities, SelfParticipant, type SessionState, SignalWire, type SignalWireOptions, StaticCredentialProvider, type Storage, Subscriber, type TextMessage, TokenRefreshError, type TransferOptions, UnexpectedError, VertoPongError, type VideoPosition, type WebRTCApiProvider, WebRTCCall, type WebRTCMediaDevices, type WebSocketAdapter, embeddableCall, isSelfParticipant, ready, version };
 //# sourceMappingURL=index.d.cts.map