@idp.global/interfaces 1.0.1 → 1.2.0

package/changelog.md

@@ -1,7 +1,21 @@
 # Changelog
 
-## Pending
+## 2026-06-10 - 1.2.0
 
+### Features
+
+- add backend token to JWT blocklist request (request/jwt)
+  - Added optional backendToken support for authenticated GET blocklist retrieval.
+  - Documented that backendToken is omitted for PUSH requests to avoid sending the secret to clients.
+
+## 2026-05-19 - 1.1.0
+
+### Features
+
+- add MFA and passkey typed request contracts (interfaces)
+  - adds TOTP, backup code, MFA challenge, passkey credential, and WebAuthn challenge data contracts
+  - extends login responses with MFA challenge metadata for password and magic-link flows
+  - exports typed request contracts for TOTP enrollment, backup codes, passkey login, and passkey MFA step-up
 
 ## 2026-05-18 - 1.0.1
 

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@idp.global/interfaces',
-    version: '1.0.1',
+    version: '1.2.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the idp.global ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/data/activity.d.ts

@@ -1,4 +1,4 @@
-export type TActivityAction = 'login' | 'logout' | 'session_created' | 'session_revoked' | 'passport_device_enrolled' | 'passport_device_revoked' | 'passport_challenge_approved' | 'passport_challenge_rejected' | 'org_created' | 'org_updated' | 'org_deleted' | 'org_ownership_transferred' | 'org_joined' | 'org_left' | 'role_changed' | 'org_app_role_mappings_updated' | 'profile_updated' | 'app_connected' | 'app_disconnected';
+export type TActivityAction = 'login' | 'logout' | 'session_created' | 'session_revoked' | 'passport_device_enrolled' | 'passport_device_revoked' | 'passport_challenge_approved' | 'passport_challenge_rejected' | 'org_created' | 'org_updated' | 'org_deleted' | 'org_ownership_transferred' | 'org_joined' | 'org_left' | 'role_changed' | 'org_app_role_mappings_updated' | 'profile_updated' | 'totp_enabled' | 'totp_disabled' | 'backup_codes_regenerated' | 'mfa_completed' | 'passkey_registered' | 'passkey_revoked' | 'passkey_login' | 'app_connected' | 'app_disconnected';
 export interface IActivityLog {
     id: string;
     data: {

package/dist_ts/data/index.d.ts

@@ -10,8 +10,10 @@ export * from './billingplan.js';
 export * from './device.js';
 export * from './jwt.js';
 export * from './loginsession.js';
+export * from './mfa.js';
 export * from './organization.js';
 export * from './paddlecheckoutdata.js';
+export * from './passkey.js';
 export * from './passportchallenge.js';
 export * from './passportdevice.js';
 export * from './passportnonce.js';

package/dist_ts/data/index.js

@@ -10,8 +10,10 @@ export * from './billingplan.js';
 export * from './device.js';
 export * from './jwt.js';
 export * from './loginsession.js';
+export * from './mfa.js';
 export * from './organization.js';
 export * from './paddlecheckoutdata.js';
+export * from './passkey.js';
 export * from './passportchallenge.js';
 export * from './passportdevice.js';
 export * from './passportnonce.js';
@@ -19,4 +21,4 @@ export * from './registrationsession.js';
 export * from './role.js';
 export * from './user.js';
 export * from './userinvitation.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLFVBQVUsQ0FBQztBQUN6QixjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLFVBQVUsQ0FBQztBQUN6QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyx5QkFBeUIsQ0FBQztBQUN4QyxjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMscUJBQXFCLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLFVBQVUsQ0FBQztBQUN6QixjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLFVBQVUsQ0FBQztBQUN6QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyx5QkFBeUIsQ0FBQztBQUN4QyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMscUJBQXFCLENBQUMifQ==

package/dist_ts/data/mfa.d.ts

@@ -0,0 +1,40 @@
+export type TMfaMethod = 'totp' | 'backupCode' | 'passkey';
+export type TMfaChallengeStatus = 'pending' | 'completed' | 'expired';
+export type TTotpCredentialStatus = 'pending' | 'active' | 'disabled';
+export interface ITotpBackupCode {
+    id: string;
+    codeHash: string;
+    usedAt?: number | null;
+    createdAt: number;
+}
+export interface ITotpCredential {
+    id: string;
+    data: {
+        userId: string;
+        status: TTotpCredentialStatus;
+        secretCiphertext: string;
+        secretIv: string;
+        secretAuthTag: string;
+        algorithm: 'sha1' | 'sha256' | 'sha512';
+        digits: 6 | 7 | 8;
+        period: number;
+        backupCodes: ITotpBackupCode[];
+        createdAt: number;
+        verifiedAt?: number | null;
+        disabledAt?: number | null;
+        lastUsedAt?: number | null;
+    };
+}
+export interface IMfaChallenge {
+    id: string;
+    data: {
+        userId: string;
+        tokenHash: string;
+        status: TMfaChallengeStatus;
+        availableMethods: TMfaMethod[];
+        primaryAuthMethod: 'password' | 'email';
+        createdAt: number;
+        expiresAt: number;
+        completedAt?: number | null;
+    };
+}

package/dist_ts/data/mfa.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWZhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZGF0YS9tZmEudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9

package/dist_ts/data/passkey.d.ts

@@ -0,0 +1,36 @@
+export type TPasskeyCredentialStatus = 'active' | 'revoked';
+export type TPasskeyChallengeType = 'registration' | 'login' | 'mfa';
+export type TPasskeyChallengeStatus = 'pending' | 'completed' | 'expired';
+export type TPasskeyTransport = 'ble' | 'cable' | 'hybrid' | 'internal' | 'nfc' | 'smart-card' | 'usb';
+export type TPasskeyDeviceType = 'singleDevice' | 'multiDevice';
+export interface IPasskeyCredential {
+    id: string;
+    data: {
+        userId: string;
+        label: string;
+        credentialId: string;
+        publicKeyBase64: string;
+        counter: number;
+        deviceType: TPasskeyDeviceType;
+        backedUp: boolean;
+        transports?: TPasskeyTransport[];
+        status: TPasskeyCredentialStatus;
+        createdAt: number;
+        lastUsedAt?: number | null;
+        revokedAt?: number | null;
+    };
+}
+export interface IWebAuthnChallenge {
+    id: string;
+    data: {
+        userId?: string | null;
+        username?: string | null;
+        mfaChallengeId?: string | null;
+        type: TPasskeyChallengeType;
+        challenge: string;
+        status: TPasskeyChallengeStatus;
+        createdAt: number;
+        expiresAt: number;
+        completedAt?: number | null;
+    };
+}

package/dist_ts/data/passkey.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGFzc2tleS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvcGFzc2tleS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/dist_ts/request/index.d.ts

@@ -6,6 +6,7 @@ export * from './authorization.js';
 export * from './billingplan.js';
 export * from './jwt.js';
 export * from './login.js';
+export * from './mfa.js';
 export * from './organization.js';
 export * from './passport.js';
 export * from './plan.js';

package/dist_ts/request/index.js

@@ -6,10 +6,11 @@ export * from './authorization.js';
 export * from './billingplan.js';
 export * from './jwt.js';
 export * from './login.js';
+export * from './mfa.js';
 export * from './organization.js';
 export * from './passport.js';
 export * from './plan.js';
 export * from './registration.js';
 export * from './user.js';
 export * from './userinvitation.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0L2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLFVBQVUsQ0FBQztBQUN6QixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxxQkFBcUIsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0L2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLFVBQVUsQ0FBQztBQUN6QixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLFVBQVUsQ0FBQztBQUN6QixjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxxQkFBcUIsQ0FBQyJ9

package/dist_ts/request/jwt.d.ts

@@ -44,6 +44,7 @@ export interface IReq_PushPublicKeyForValidation extends plugins.typedRequestInt
  *
  * **For GET (client fires):**
  * - Fire with empty/undefined `blockedJwtIds` to request the full blocklist
+ * - Include `backendToken` to authenticate as a backend service
  * - Response contains the complete list of blocked JWT IDs
  * - Use `IdpClient.requests.getJwtIdBlocklist` for this direction
  *
@@ -55,6 +56,13 @@ export interface IReq_PushPublicKeyForValidation extends plugins.typedRequestInt
 export interface IReq_PushOrGetJwtIdBlocklist extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_PushOrGetJwtIdBlocklist> {
     method: 'pushOrGetJwtIdBlocklist';
     request: {
+        /**
+         * Authenticates the requesting backend service in the GET direction
+         * (Client → idp.global). Required by the idp.global handler.
+         * Omitted in the PUSH direction (idp.global → Client) so the secret
+         * never travels to connected clients.
+         */
+        backendToken?: string;
         blockedJwtIds?: string[];
     };
     response: {

package/dist_ts/request/login.d.ts

@@ -9,6 +9,8 @@ export interface IReq_LoginWithEmailOrUsernameAndPassword extends plugins.typedR
     response: {
         refreshToken?: string;
         twoFaNeeded: boolean;
+        mfaChallengeToken?: string;
+        availableMfaMethods?: data.TMfaMethod[];
     };
 }
 export interface IReq_LoginWithEmail extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_LoginWithEmailOrUsernameAndPassword> {
@@ -28,7 +30,10 @@ export interface IReq_LoginWithEmailAfterEmailTokenAquired extends plugins.typed
         token: string;
     };
     response: {
-        refreshToken: string;
+        refreshToken?: string;
+        twoFaNeeded?: boolean;
+        mfaChallengeToken?: string;
+        availableMfaMethods?: data.TMfaMethod[];
     };
 }
 /**

package/dist_ts/request/mfa.d.ts

@@ -0,0 +1,143 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+export interface IReq_GetMfaStatus extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_GetMfaStatus> {
+    method: 'getMfaStatus';
+    request: {
+        jwt: string;
+    };
+    response: {
+        totpEnabled: boolean;
+        backupCodesRemaining: number;
+        passkeys: data.IPasskeyCredential[];
+        availableMethods: data.TMfaMethod[];
+    };
+}
+export interface IReq_StartTotpEnrollment extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_StartTotpEnrollment> {
+    method: 'startTotpEnrollment';
+    request: {
+        jwt: string;
+    };
+    response: {
+        credentialId: string;
+        secret: string;
+        otpauthUrl: string;
+    };
+}
+export interface IReq_FinishTotpEnrollment extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_FinishTotpEnrollment> {
+    method: 'finishTotpEnrollment';
+    request: {
+        jwt: string;
+        credentialId: string;
+        code: string;
+    };
+    response: {
+        success: boolean;
+        backupCodes: string[];
+    };
+}
+export interface IReq_DisableTotp extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_DisableTotp> {
+    method: 'disableTotp';
+    request: {
+        jwt: string;
+        code: string;
+    };
+    response: {
+        success: boolean;
+    };
+}
+export interface IReq_RegenerateBackupCodes extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_RegenerateBackupCodes> {
+    method: 'regenerateBackupCodes';
+    request: {
+        jwt: string;
+        code: string;
+    };
+    response: {
+        backupCodes: string[];
+    };
+}
+export interface IReq_VerifyMfaChallenge extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_VerifyMfaChallenge> {
+    method: 'verifyMfaChallenge';
+    request: {
+        mfaChallengeToken: string;
+        method: Extract<data.TMfaMethod, 'totp' | 'backupCode'>;
+        code: string;
+    };
+    response: {
+        refreshToken: string;
+    };
+}
+export interface IReq_StartPasskeyRegistration extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_StartPasskeyRegistration> {
+    method: 'startPasskeyRegistration';
+    request: {
+        jwt: string;
+        label?: string;
+    };
+    response: {
+        challengeId: string;
+        options: Record<string, any>;
+    };
+}
+export interface IReq_FinishPasskeyRegistration extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_FinishPasskeyRegistration> {
+    method: 'finishPasskeyRegistration';
+    request: {
+        jwt: string;
+        challengeId: string;
+        label?: string;
+        response: Record<string, any>;
+    };
+    response: {
+        success: boolean;
+        passkey: data.IPasskeyCredential;
+    };
+}
+export interface IReq_RevokePasskey extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_RevokePasskey> {
+    method: 'revokePasskey';
+    request: {
+        jwt: string;
+        passkeyId: string;
+    };
+    response: {
+        success: boolean;
+    };
+}
+export interface IReq_StartPasskeyLogin extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_StartPasskeyLogin> {
+    method: 'startPasskeyLogin';
+    request: {
+        username?: string;
+    };
+    response: {
+        challengeId: string;
+        options: Record<string, any>;
+    };
+}
+export interface IReq_FinishPasskeyLogin extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_FinishPasskeyLogin> {
+    method: 'finishPasskeyLogin';
+    request: {
+        challengeId: string;
+        response: Record<string, any>;
+    };
+    response: {
+        refreshToken: string;
+    };
+}
+export interface IReq_StartPasskeyMfa extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_StartPasskeyMfa> {
+    method: 'startPasskeyMfa';
+    request: {
+        mfaChallengeToken: string;
+    };
+    response: {
+        challengeId: string;
+        options: Record<string, any>;
+    };
+}
+export interface IReq_FinishPasskeyMfa extends plugins.typedRequestInterfaces.implementsTR<plugins.typedRequestInterfaces.ITypedRequest, IReq_FinishPasskeyMfa> {
+    method: 'finishPasskeyMfa';
+    request: {
+        mfaChallengeToken: string;
+        challengeId: string;
+        response: Record<string, any>;
+    };
+    response: {
+        refreshToken: string;
+    };
+}

package/dist_ts/request/mfa.js

@@ -0,0 +1,3 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibWZhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvcmVxdWVzdC9tZmEudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUM7QUFDekMsT0FBTyxLQUFLLElBQUksTUFBTSxrQkFBa0IsQ0FBQyJ9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idp.global/interfaces",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the idp.global ecosystem.",
   "exports": {
@@ -14,11 +14,11 @@
     "@tsclass/tsclass": "^9.5.1"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.1",
-    "@git.zone/tsdoc": "^2.0.5",
+    "@git.zone/tsbuild": "^4.4.2",
+    "@git.zone/tsdoc": "^2.0.6",
     "@git.zone/tsrun": "^2.0.4",
     "@git.zone/tstest": "^3.6.6",
-    "@types/node": "^25.9.0"
+    "@types/node": "^25.9.2"
   },
   "files": [
     "ts/**/*",

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@idp.global/interfaces',
-  version: '1.0.1',
+  version: '1.2.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the idp.global ecosystem.'
 }

package/ts/data/activity.ts

@@ -16,6 +16,13 @@ export type TActivityAction =
   | 'role_changed'
   | 'org_app_role_mappings_updated'
   | 'profile_updated'
+  | 'totp_enabled'
+  | 'totp_disabled'
+  | 'backup_codes_regenerated'
+  | 'mfa_completed'
+  | 'passkey_registered'
+  | 'passkey_revoked'
+  | 'passkey_login'
   | 'app_connected'
   | 'app_disconnected';
 

package/ts/data/index.ts

@@ -10,8 +10,10 @@ export * from './billingplan.js';
 export * from './device.js';
 export * from './jwt.js';
 export * from './loginsession.js';
+export * from './mfa.js';
 export * from './organization.js';
 export * from './paddlecheckoutdata.js';
+export * from './passkey.js';
 export * from './passportchallenge.js';
 export * from './passportdevice.js';
 export * from './passportnonce.js';

package/ts/data/mfa.ts

@@ -0,0 +1,45 @@
+export type TMfaMethod = 'totp' | 'backupCode' | 'passkey';
+
+export type TMfaChallengeStatus = 'pending' | 'completed' | 'expired';
+
+export type TTotpCredentialStatus = 'pending' | 'active' | 'disabled';
+
+export interface ITotpBackupCode {
+  id: string;
+  codeHash: string;
+  usedAt?: number | null;
+  createdAt: number;
+}
+
+export interface ITotpCredential {
+  id: string;
+  data: {
+    userId: string;
+    status: TTotpCredentialStatus;
+    secretCiphertext: string;
+    secretIv: string;
+    secretAuthTag: string;
+    algorithm: 'sha1' | 'sha256' | 'sha512';
+    digits: 6 | 7 | 8;
+    period: number;
+    backupCodes: ITotpBackupCode[];
+    createdAt: number;
+    verifiedAt?: number | null;
+    disabledAt?: number | null;
+    lastUsedAt?: number | null;
+  };
+}
+
+export interface IMfaChallenge {
+  id: string;
+  data: {
+    userId: string;
+    tokenHash: string;
+    status: TMfaChallengeStatus;
+    availableMethods: TMfaMethod[];
+    primaryAuthMethod: 'password' | 'email';
+    createdAt: number;
+    expiresAt: number;
+    completedAt?: number | null;
+  };
+}

package/ts/data/passkey.ts

@@ -0,0 +1,49 @@
+export type TPasskeyCredentialStatus = 'active' | 'revoked';
+
+export type TPasskeyChallengeType = 'registration' | 'login' | 'mfa';
+
+export type TPasskeyChallengeStatus = 'pending' | 'completed' | 'expired';
+
+export type TPasskeyTransport =
+  | 'ble'
+  | 'cable'
+  | 'hybrid'
+  | 'internal'
+  | 'nfc'
+  | 'smart-card'
+  | 'usb';
+
+export type TPasskeyDeviceType = 'singleDevice' | 'multiDevice';
+
+export interface IPasskeyCredential {
+  id: string;
+  data: {
+    userId: string;
+    label: string;
+    credentialId: string;
+    publicKeyBase64: string;
+    counter: number;
+    deviceType: TPasskeyDeviceType;
+    backedUp: boolean;
+    transports?: TPasskeyTransport[];
+    status: TPasskeyCredentialStatus;
+    createdAt: number;
+    lastUsedAt?: number | null;
+    revokedAt?: number | null;
+  };
+}
+
+export interface IWebAuthnChallenge {
+  id: string;
+  data: {
+    userId?: string | null;
+    username?: string | null;
+    mfaChallengeId?: string | null;
+    type: TPasskeyChallengeType;
+    challenge: string;
+    status: TPasskeyChallengeStatus;
+    createdAt: number;
+    expiresAt: number;
+    completedAt?: number | null;
+  };
+}

package/ts/request/index.ts

@@ -6,6 +6,7 @@ export * from './authorization.js';
 export * from './billingplan.js';
 export * from './jwt.js';
 export * from './login.js';
+export * from './mfa.js';
 export * from './organization.js';
 export * from './passport.js';
 export * from './plan.js';

package/ts/request/jwt.ts

@@ -56,6 +56,7 @@ export interface IReq_PushPublicKeyForValidation
  *
  * **For GET (client fires):**
  * - Fire with empty/undefined `blockedJwtIds` to request the full blocklist
+ * - Include `backendToken` to authenticate as a backend service
  * - Response contains the complete list of blocked JWT IDs
  * - Use `IdpClient.requests.getJwtIdBlocklist` for this direction
  *
@@ -71,6 +72,13 @@ export interface IReq_PushOrGetJwtIdBlocklist
   > {
   method: 'pushOrGetJwtIdBlocklist';
   request: {
+    /**
+     * Authenticates the requesting backend service in the GET direction
+     * (Client → idp.global). Required by the idp.global handler.
+     * Omitted in the PUSH direction (idp.global → Client) so the secret
+     * never travels to connected clients.
+     */
+    backendToken?: string;
     blockedJwtIds?: string[];
   };
   response: {

package/ts/request/login.ts

@@ -14,6 +14,8 @@ export interface IReq_LoginWithEmailOrUsernameAndPassword
   response: {
     refreshToken?: string;
     twoFaNeeded: boolean;
+    mfaChallengeToken?: string;
+    availableMfaMethods?: data.TMfaMethod[];
   };
 }
 
@@ -43,7 +45,10 @@ export interface IReq_LoginWithEmailAfterEmailTokenAquired
     token: string;
   };
   response: {
-    refreshToken: string;
+    refreshToken?: string;
+    twoFaNeeded?: boolean;
+    mfaChallengeToken?: string;
+    availableMfaMethods?: data.TMfaMethod[];
   };
 }
 

package/ts/request/mfa.ts

@@ -0,0 +1,208 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_GetMfaStatus
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_GetMfaStatus
+  > {
+  method: 'getMfaStatus';
+  request: {
+    jwt: string;
+  };
+  response: {
+    totpEnabled: boolean;
+    backupCodesRemaining: number;
+    passkeys: data.IPasskeyCredential[];
+    availableMethods: data.TMfaMethod[];
+  };
+}
+
+export interface IReq_StartTotpEnrollment
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_StartTotpEnrollment
+  > {
+  method: 'startTotpEnrollment';
+  request: {
+    jwt: string;
+  };
+  response: {
+    credentialId: string;
+    secret: string;
+    otpauthUrl: string;
+  };
+}
+
+export interface IReq_FinishTotpEnrollment
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_FinishTotpEnrollment
+  > {
+  method: 'finishTotpEnrollment';
+  request: {
+    jwt: string;
+    credentialId: string;
+    code: string;
+  };
+  response: {
+    success: boolean;
+    backupCodes: string[];
+  };
+}
+
+export interface IReq_DisableTotp
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_DisableTotp
+  > {
+  method: 'disableTotp';
+  request: {
+    jwt: string;
+    code: string;
+  };
+  response: {
+    success: boolean;
+  };
+}
+
+export interface IReq_RegenerateBackupCodes
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_RegenerateBackupCodes
+  > {
+  method: 'regenerateBackupCodes';
+  request: {
+    jwt: string;
+    code: string;
+  };
+  response: {
+    backupCodes: string[];
+  };
+}
+
+export interface IReq_VerifyMfaChallenge
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_VerifyMfaChallenge
+  > {
+  method: 'verifyMfaChallenge';
+  request: {
+    mfaChallengeToken: string;
+    method: Extract<data.TMfaMethod, 'totp' | 'backupCode'>;
+    code: string;
+  };
+  response: {
+    refreshToken: string;
+  };
+}
+
+export interface IReq_StartPasskeyRegistration
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_StartPasskeyRegistration
+  > {
+  method: 'startPasskeyRegistration';
+  request: {
+    jwt: string;
+    label?: string;
+  };
+  response: {
+    challengeId: string;
+    options: Record<string, any>;
+  };
+}
+
+export interface IReq_FinishPasskeyRegistration
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_FinishPasskeyRegistration
+  > {
+  method: 'finishPasskeyRegistration';
+  request: {
+    jwt: string;
+    challengeId: string;
+    label?: string;
+    response: Record<string, any>;
+  };
+  response: {
+    success: boolean;
+    passkey: data.IPasskeyCredential;
+  };
+}
+
+export interface IReq_RevokePasskey
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_RevokePasskey
+  > {
+  method: 'revokePasskey';
+  request: {
+    jwt: string;
+    passkeyId: string;
+  };
+  response: {
+    success: boolean;
+  };
+}
+
+export interface IReq_StartPasskeyLogin
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_StartPasskeyLogin
+  > {
+  method: 'startPasskeyLogin';
+  request: {
+    username?: string;
+  };
+  response: {
+    challengeId: string;
+    options: Record<string, any>;
+  };
+}
+
+export interface IReq_FinishPasskeyLogin
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_FinishPasskeyLogin
+  > {
+  method: 'finishPasskeyLogin';
+  request: {
+    challengeId: string;
+    response: Record<string, any>;
+  };
+  response: {
+    refreshToken: string;
+  };
+}
+
+export interface IReq_StartPasskeyMfa
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_StartPasskeyMfa
+  > {
+  method: 'startPasskeyMfa';
+  request: {
+    mfaChallengeToken: string;
+  };
+  response: {
+    challengeId: string;
+    options: Record<string, any>;
+  };
+}
+
+export interface IReq_FinishPasskeyMfa
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_FinishPasskeyMfa
+  > {
+  method: 'finishPasskeyMfa';
+  request: {
+    mfaChallengeToken: string;
+    challengeId: string;
+    response: Record<string, any>;
+  };
+  response: {
+    refreshToken: string;
+  };
+}