@hawcx/oauth-client 0.2.0 → 5.1.0

package/dist/delegation/hawcx.d.ts

@@ -1,254 +1,89 @@
 /**
- * Hawcx-specific delegation client with high-level convenience methods.
- *
- * This module provides a streamlined API for common Hawcx operations like
- * MFA configuration, user management, and device operations. All cryptographic
- * operations (encryption, signing, verification) are handled automatically.
- */
-import { Signer } from './client';
-import { Verifier, EciesX25519Encryptor, EciesX25519Decryptor } from './crypto';
-/**
- * Supported MFA methods for Hawcx authentication.
- *
- * This enum ensures type safety and prevents typos when specifying MFA methods.
- *
- * @example
- * ```typescript
- * import { MfaMethod } from '@hawcx/oauth-client';
- *
- * // Use enum for type safety
- * await client.initiateMfaChange({
- *   userid: "user@example.com",
- *   mfaMethod: MfaMethod.SMS,  // Type-safe!
- *   phoneNumber: "+15551234567"
- * });
- *
- * // String values still work for backwards compatibility
- * await client.initiateMfaChange({
- *   userid: "user@example.com",
- *   mfaMethod: "sms",  // Also works
- *   phoneNumber: "+15551234567"
- * });
- * ```
+ * Hawcx delegation client with ergonomic, high-level operations.
  */
+import { DelegationTransport } from './transport';
+import { DelegationKeyMaterial } from './factory';
 export declare enum MfaMethod {
     EMAIL = "email",
     SMS = "sms",
     TOTP = "totp"
 }
-/**
- * Options for initializing Hawcx delegation client from keys
- */
-export interface HawcxClientFromKeysOptions {
-    /** Service Provider's Ed25519 private key (PEM format) */
-    spSigningKey: string;
-    /** Service Provider's X25519 private key (PEM format) */
-    spEncryptionKey: string;
-    /** IDP's Ed25519 public key (PEM format) */
-    idpVerifyKey: string;
-    /** IDP's X25519 public key (PEM format) */
-    idpEncryptionKey: string;
-    /** Hawcx API base URL (e.g., "https://example.hawcx.com") */
+type JsonObject = Record<string, unknown>;
+export interface DelegationClientBaseOptions {
+    /** Hawcx API base URL (e.g., "https://api.hawcx.com") */
     baseUrl: string;
-    /** Service Provider identifier (usually OAuth client_id) */
-    spId: string;
-    /** Optional Hawcx API key */
+    /** Optional Hawcx API key (for additional authentication) */
     apiKey?: string;
     /** Request timeout in seconds (default: 15) */
-    timeout?: number;
-    /** Internal - Key ID for SP signatures (default: "hawcx", do not change) */
-    kid?: string;
-    /** Internal - Key ID for IDP verification (default: "hawcx", do not change) */
-    idpKid?: string;
+    timeoutSeconds?: number;
+    /** Allowed response timestamp skew in seconds (default: 300) */
+    clockSkewSeconds?: number;
 }
-/**
- * Options for initiating MFA change
- */
-export interface InitiateMfaChangeOptions {
+export interface DelegationClientSecretKeyOptions extends DelegationClientBaseOptions {
+    /** Hawcx secret key (credential blob). */
+    secretKey: string;
+}
+export type DelegationClientKeyOptions = DelegationClientBaseOptions & DelegationKeyMaterial;
+export interface MfaInitiateOptions {
     /** User identifier (typically email address) */
-    userid: string;
+    userId: string;
     /** MFA method to configure (MfaMethod enum or 'email', 'sms', 'totp' string) */
     mfaMethod: MfaMethod | string;
-    /** Phone number with country code (required for SMS, e.g., "+15551234567") */
+    /** Phone number with country code (required for SMS) */
     phoneNumber?: string;
     /** Target MFA method after verification (optional) */
     mfaChangeTo?: MfaMethod | string;
 }
-/**
- * Options for verifying MFA change
- */
-export interface VerifyMfaChangeOptions {
+export interface MfaVerifyOptions {
     /** User identifier (must match initiate request) */
-    userid: string;
-    /** Session ID from initiateMfaChange response */
+    userId: string;
+    /** Session ID from initiate response */
     sessionId: string;
     /** One-time password entered by user (6 digits) */
     otp: string;
 }
-/**
- * High-level client for Hawcx delegation operations.
- *
- * This client provides simplified methods for common Hawcx operations:
- * - MFA configuration (email, SMS, TOTP)
- * - User credential management
- * - Device operations
- *
- * All requests are automatically encrypted (ECIES) and signed (Ed25519/RSA-PSS).
- * All responses are automatically verified and decrypted.
- *
- * @example
- * ```typescript
- * // Initialize from keys
- * const client = HawcxDelegationClient.fromKeys({
- *   spSigningKey: process.env.SP_SIGNING_KEY!,
- *   spEncryptionKey: process.env.SP_ENCRYPTION_KEY!,
- *   idpVerifyKey: process.env.IDP_VERIFY_KEY!,
- *   idpEncryptionKey: process.env.IDP_ENCRYPTION_KEY!,
- *   baseUrl: 'https://example.hawcx.com',
- *   spId: 'my-client-id'
- * });
- *
- * // Initiate SMS MFA setup
- * const result = await client.initiateMfaChange({
- *   userid: "user@example.com",
- *   mfaMethod: "sms",
- *   phoneNumber: "+15551234567"
- * });
- * console.log(result.session_id);
- *
- * // Verify OTP
- * await client.verifyMfaChange({
- *   userid: "user@example.com",
- *   sessionId: result.session_id,
- *   otp: "123456"
- * });
- * ```
- */
-export declare class HawcxDelegationClient {
-    private client;
+export interface DeviceOperationOptions {
+    /** User identifier (typically email address) */
+    userId: string;
+    /** Device identifier (h2index) */
+    deviceId: string;
+}
+export interface DelegationRequestOptions<TPayload extends JsonObject> {
+    /** API endpoint path (e.g., "/hc_auth/v5/update/initiate") */
+    endpoint: string;
+    /** Request payload dictionary to be encrypted and sent */
+    payload: TPayload;
+    /** If true, prepends base_url to endpoint (default: true) */
+    includeBaseUrl?: boolean;
+    /** Optional additional HTTP headers (e.g., API keys) */
+    headers?: Record<string, string>;
+}
+export declare class DelegationClient {
+    private transport;
     private apiKey?;
-    baseUrl: string;
-    spId: string;
+    readonly baseUrl: string;
     constructor(options: {
-        baseUrl: string;
-        signer: Signer;
-        verifier: Verifier;
-        encryptor: EciesX25519Encryptor;
-        decryptor: EciesX25519Decryptor;
-        spId: string;
+        transport: DelegationTransport;
         apiKey?: string;
-        timeout?: number;
+        baseUrl: string;
     });
-    /**
-     * Create client from explicit key values (recommended).
-     *
-     * This method allows the application to load keys from any source
-     * (env vars, config files, secrets manager, etc.) and pass them
-     * as values to the SDK.
-     *
-     * @param options - Configuration options
-     * @returns Configured HawcxDelegationClient instance
-     * @throws DelegationRequestError if key initialization fails
-     *
-     * @example
-     * ```typescript
-     * import * as process from 'process';
-     *
-     * // App controls how to load keys
-     * const client = HawcxDelegationClient.fromKeys({
-     *   spSigningKey: process.env.MY_SIGNING_KEY!,
-     *   spEncryptionKey: process.env.MY_ENCRYPTION_KEY!,
-     *   idpVerifyKey: process.env.IDP_VERIFY_KEY!,
-     *   idpEncryptionKey: process.env.IDP_ENCRYPT_KEY!,
-     *   baseUrl: process.env.HAWCX_URL!,
-     *   spId: process.env.MY_CLIENT_ID!
-     * });
-     * ```
-     */
-    static fromKeys(options: HawcxClientFromKeysOptions): HawcxDelegationClient;
-    /**
-     * Build Hawcx API authentication headers
-     */
+    static fromSecretKey(options: DelegationClientSecretKeyOptions): DelegationClient;
+    static fromKeys(options: DelegationClientKeyOptions): DelegationClient;
     private buildAuthHeaders;
-    /**
-     * Initiate MFA setup or change for a user.
-     *
-     * This method starts the MFA enrollment/update process by sending an OTP
-     * to the user via their chosen method (email, SMS, or generating a TOTP secret).
-     *
-     * @param options - MFA initiation configuration
-     * @returns Dictionary containing session_id and optional TOTP details
-     * @throws DelegationRequestError if request fails or parameters are invalid
-     * @throws Error if SMS method specified without phone_number
-     *
-     * @example
-     * ```typescript
-     * import { MfaMethod } from '@hawcx/oauth-client';
-     *
-     * // Email MFA (with enum - recommended!)
-     * const result = await client.initiateMfaChange({
-     *   userid: "user@example.com",
-     *   mfaMethod: MfaMethod.EMAIL
-     * });
-     *
-     * // SMS MFA (string also works)
-     * const result = await client.initiateMfaChange({
-     *   userid: "user@example.com",
-     *   mfaMethod: "sms",
-     *   phoneNumber: "+15551234567"
-     * });
-     *
-     * // TOTP MFA
-     * const result = await client.initiateMfaChange({
-     *   userid: "user@example.com",
-     *   mfaMethod: MfaMethod.TOTP
-     * });
-     * console.log(`Scan QR code: ${result.otpauth_uri}`);
-     * ```
-     */
-    initiateMfaChange(options: InitiateMfaChangeOptions): Promise<Record<string, any>>;
-    /**
-     * Verify OTP and complete MFA configuration change.
-     *
-     * This method verifies the OTP sent to the user and completes the MFA
-     * enrollment/update process.
-     *
-     * @param options - MFA verification configuration
-     * @returns Dictionary containing success message and optional mfa_changed_to
-     * @throws DelegationRequestError if verification fails
-     * @throws Error if OTP format is invalid
-     *
-     * @example
-     * ```typescript
-     * // Get OTP from user
-     * const otp = getUserInput();
-     *
-     * // Verify and complete MFA setup
-     * const result = await client.verifyMfaChange({
-     *   userid: "user@example.com",
-     *   sessionId: sessionId,
-     *   otp: otp
-     * });
-     * console.log(`MFA updated: ${result.detail}`);
-     * ```
-     */
-    verifyMfaChange(options: VerifyMfaChangeOptions): Promise<Record<string, any>>;
-    /**
-     * Get user's stored credentials and MFA status.
-     *
-     * This method retrieves the user's credentials from Hawcx, including
-     * their current MFA configuration.
-     *
-     * @param userid - User identifier
-     * @returns Dictionary containing user credentials and MFA status
-     *
-     * @example
-     * ```typescript
-     * const creds = await client.getUserCredentials("user@example.com");
-     * console.log(`MFA method: ${creds.mfa_method}`);
-     * console.log(`Phone: ${creds.contact}`);
-     * ```
-     */
-    getUserCredentials(userid: string): Promise<Record<string, any>>;
+    request<TReq extends JsonObject, TRes extends JsonObject>(options: DelegationRequestOptions<TReq>): Promise<TRes>;
+    readonly mfa: {
+        initiate: (options: MfaInitiateOptions) => Promise<JsonObject>;
+        verify: (options: MfaVerifyOptions) => Promise<JsonObject>;
+    };
+    readonly users: {
+        getCredentials: (userId: string) => Promise<JsonObject>;
+    };
+    readonly devices: {
+        list: (userId: string) => Promise<JsonObject>;
+        revoke: (options: DeviceOperationOptions) => Promise<JsonObject>;
+        unrevoke: (options: DeviceOperationOptions) => Promise<JsonObject>;
+        delete: (options: DeviceOperationOptions) => Promise<JsonObject>;
+    };
 }
+export {};
 //# sourceMappingURL=hawcx.d.ts.map

package/dist/delegation/hawcx.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hawcx.d.ts","sourceRoot":"","sources":["../../src/delegation/hawcx.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAuB,MAAM,EAAE,MAAM,UAAU,CAAC;AACvD,OAAO,EAEL,QAAQ,EACR,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,UAAU,CAAC;AAGlB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,oBAAY,SAAS;IACnB,KAAK,UAAU;IACf,GAAG,QAAQ;IACX,IAAI,SAAS;CACd;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,0DAA0D;IAC1D,YAAY,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,eAAe,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,gBAAgB,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,SAAS,EAAE,SAAS,GAAG,MAAM,CAAC;IAC9B,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,WAAW,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAsB;IACpC,OAAO,CAAC,MAAM,CAAC,CAAS;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;gBAER,OAAO,EAAE;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,QAAQ,CAAC;QACnB,SAAS,EAAE,oBAAoB,CAAC;QAChC,SAAS,EAAE,oBAAoB,CAAC;QAChC,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB;IAeD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,0BAA0B,GAAG,qBAAqB;IAqC3E;;OAEG;IACH,OAAO,CAAC,gBAAgB;IASxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAyDxF;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAgCpF;;;;;;;;;;;;;;;OAeG;IACG,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAmBvE"}
+{"version":3,"file":"hawcx.d.ts","sourceRoot":"","sources":["../../src/delegation/hawcx.ts"],"names":[],"mappings":"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"}