authvital-sdk 0.1.1-dev.3.cefb119.0

package/dist/webhook-router-DdfXLtHa.d.ts

@@ -0,0 +1,461 @@
+declare const SYNC_EVENT_TYPES: {
+    readonly INVITE_CREATED: "invite.created";
+    readonly INVITE_ACCEPTED: "invite.accepted";
+    readonly INVITE_DELETED: "invite.deleted";
+    readonly INVITE_EXPIRED: "invite.expired";
+    readonly SUBJECT_CREATED: "subject.created";
+    readonly SUBJECT_UPDATED: "subject.updated";
+    readonly SUBJECT_DELETED: "subject.deleted";
+    readonly SUBJECT_DEACTIVATED: "subject.deactivated";
+    readonly MEMBER_JOINED: "member.joined";
+    readonly MEMBER_LEFT: "member.left";
+    readonly MEMBER_ROLE_CHANGED: "member.role_changed";
+    readonly MEMBER_SUSPENDED: "member.suspended";
+    readonly MEMBER_ACTIVATED: "member.activated";
+    readonly APP_ACCESS_GRANTED: "app_access.granted";
+    readonly APP_ACCESS_REVOKED: "app_access.revoked";
+    readonly APP_ACCESS_ROLE_CHANGED: "app_access.role_changed";
+    readonly LICENSE_ASSIGNED: "license.assigned";
+    readonly LICENSE_REVOKED: "license.revoked";
+    readonly LICENSE_CHANGED: "license.changed";
+};
+type SyncEventType = (typeof SYNC_EVENT_TYPES)[keyof typeof SYNC_EVENT_TYPES];
+interface BaseEvent<T extends SyncEventType, D> {
+    id: string;
+    type: T;
+    timestamp: string;
+    tenant_id: string;
+    application_id: string;
+    data: D;
+}
+interface InviteData {
+    invite_id: string;
+    membership_id: string;
+    email: string;
+    tenant_roles: string[];
+    invited_by_sub?: string;
+    expires_at?: string;
+}
+type InviteCreatedEvent = BaseEvent<'invite.created', InviteData>;
+type InviteAcceptedEvent = BaseEvent<'invite.accepted', InviteData & {
+    sub: string;
+    given_name?: string;
+    family_name?: string;
+}>;
+type InviteDeletedEvent = BaseEvent<'invite.deleted', Pick<InviteData, 'invite_id' | 'membership_id' | 'email'>>;
+type InviteExpiredEvent = BaseEvent<'invite.expired', Pick<InviteData, 'invite_id' | 'membership_id' | 'email'>>;
+interface SubjectData {
+    sub: string;
+    email?: string;
+    given_name?: string;
+    family_name?: string;
+    subject_type?: 'user' | 'service_account' | 'machine';
+}
+type SubjectCreatedEvent = BaseEvent<'subject.created', SubjectData>;
+type SubjectUpdatedEvent = BaseEvent<'subject.updated', SubjectData & {
+    changed_fields: string[];
+}>;
+type SubjectDeletedEvent = BaseEvent<'subject.deleted', Pick<SubjectData, 'sub' | 'email'>>;
+type SubjectDeactivatedEvent = BaseEvent<'subject.deactivated', Pick<SubjectData, 'sub' | 'email'>>;
+interface MemberData {
+    membership_id: string;
+    sub: string;
+    email?: string;
+    tenant_roles: string[];
+}
+type MemberJoinedEvent = BaseEvent<'member.joined', MemberData & {
+    given_name?: string;
+    family_name?: string;
+}>;
+type MemberLeftEvent = BaseEvent<'member.left', Pick<MemberData, 'membership_id' | 'sub' | 'email'>>;
+type MemberRoleChangedEvent = BaseEvent<'member.role_changed', MemberData & {
+    previous_roles: string[];
+}>;
+type MemberSuspendedEvent = BaseEvent<'member.suspended', Pick<MemberData, 'membership_id' | 'sub' | 'email'>>;
+type MemberActivatedEvent = BaseEvent<'member.activated', Pick<MemberData, 'membership_id' | 'sub' | 'email'>>;
+interface AppAccessData {
+    membership_id: string;
+    sub: string;
+    email?: string;
+    role_id: string;
+    role_name: string;
+    role_slug: string;
+}
+type AppAccessGrantedEvent = BaseEvent<'app_access.granted', AppAccessData & {
+    given_name?: string;
+    family_name?: string;
+}>;
+type AppAccessRevokedEvent = BaseEvent<'app_access.revoked', Pick<AppAccessData, 'membership_id' | 'sub' | 'email'>>;
+/**
+ * @deprecated Use AppAccessRevokedEvent instead. This alias exists for backwards compatibility.
+ */
+type AppAccessDeactivatedEvent = AppAccessRevokedEvent;
+type AppAccessRoleChangedEvent = BaseEvent<'app_access.role_changed', AppAccessData & {
+    previous_role_id: string;
+    previous_role_name: string;
+    previous_role_slug: string;
+}>;
+interface LicenseData {
+    assignment_id: string;
+    sub: string;
+    email?: string;
+    license_type_id: string;
+    license_type_name: string;
+}
+type LicenseAssignedEvent = BaseEvent<'license.assigned', LicenseData>;
+type LicenseRevokedEvent = BaseEvent<'license.revoked', Pick<LicenseData, 'assignment_id' | 'sub' | 'email'>>;
+type LicenseChangedEvent = BaseEvent<'license.changed', LicenseData & {
+    previous_license_type_id: string;
+    previous_license_type_name: string;
+}>;
+type SyncEvent = InviteCreatedEvent | InviteAcceptedEvent | InviteDeletedEvent | InviteExpiredEvent | SubjectCreatedEvent | SubjectUpdatedEvent | SubjectDeletedEvent | SubjectDeactivatedEvent | MemberJoinedEvent | MemberLeftEvent | MemberRoleChangedEvent | MemberSuspendedEvent | MemberActivatedEvent | AppAccessGrantedEvent | AppAccessRevokedEvent | AppAccessRoleChangedEvent | LicenseAssignedEvent | LicenseRevokedEvent | LicenseChangedEvent;
+declare function isInviteEvent(event: SyncEvent): event is InviteCreatedEvent | InviteAcceptedEvent | InviteDeletedEvent | InviteExpiredEvent;
+declare function isSubjectEvent(event: SyncEvent): event is SubjectCreatedEvent | SubjectUpdatedEvent | SubjectDeletedEvent | SubjectDeactivatedEvent;
+declare function isMemberEvent(event: SyncEvent): event is MemberJoinedEvent | MemberLeftEvent | MemberRoleChangedEvent | MemberSuspendedEvent | MemberActivatedEvent;
+declare function isAppAccessEvent(event: SyncEvent): event is AppAccessGrantedEvent | AppAccessRevokedEvent | AppAccessDeactivatedEvent | AppAccessRoleChangedEvent;
+declare function isLicenseEvent(event: SyncEvent): event is LicenseAssignedEvent | LicenseRevokedEvent | LicenseChangedEvent;
+
+/**
+ * Interface for handling invitation events
+ * Implement only the methods you need - all have default no-op implementations
+ */
+interface IInviteEventHandler {
+    onInviteCreated?(event: InviteCreatedEvent): Promise<void> | void;
+    onInviteAccepted?(event: InviteAcceptedEvent): Promise<void> | void;
+    onInviteDeleted?(event: InviteDeletedEvent): Promise<void> | void;
+    onInviteExpired?(event: InviteExpiredEvent): Promise<void> | void;
+}
+/**
+ * Interface for handling subject events (users, service accounts, machines)
+ */
+interface ISubjectEventHandler {
+    onSubjectCreated?(event: SubjectCreatedEvent): Promise<void> | void;
+    onSubjectUpdated?(event: SubjectUpdatedEvent): Promise<void> | void;
+    onSubjectDeleted?(event: SubjectDeletedEvent): Promise<void> | void;
+    onSubjectDeactivated?(event: SubjectDeactivatedEvent): Promise<void> | void;
+}
+/**
+ * Interface for handling membership events
+ */
+interface IMemberEventHandler {
+    onMemberJoined?(event: MemberJoinedEvent): Promise<void> | void;
+    onMemberLeft?(event: MemberLeftEvent): Promise<void> | void;
+    onMemberRoleChanged?(event: MemberRoleChangedEvent): Promise<void> | void;
+    onMemberSuspended?(event: MemberSuspendedEvent): Promise<void> | void;
+    onMemberActivated?(event: MemberActivatedEvent): Promise<void> | void;
+}
+/**
+ * Interface for handling app access events
+ */
+interface IAppAccessEventHandler {
+    onAppAccessGranted?(event: AppAccessGrantedEvent): Promise<void> | void;
+    onAppAccessRevoked?(event: AppAccessRevokedEvent): Promise<void> | void;
+    /**
+     * @deprecated Use onAppAccessRevoked instead. This method exists for backwards compatibility
+     * and will delegate to onAppAccessRevoked if implemented.
+     */
+    onAppAccessDeactivated?(event: AppAccessRevokedEvent): Promise<void> | void;
+    onAppAccessRoleChanged?(event: AppAccessRoleChangedEvent): Promise<void> | void;
+}
+/**
+ * Interface for handling license events
+ */
+interface ILicenseEventHandler {
+    onLicenseAssigned?(event: LicenseAssignedEvent): Promise<void> | void;
+    onLicenseRevoked?(event: LicenseRevokedEvent): Promise<void> | void;
+    onLicenseChanged?(event: LicenseChangedEvent): Promise<void> | void;
+}
+/**
+ * Combined interface for all events
+ * Extend this if you want to handle everything in one class
+ */
+interface IAuthVitalEventHandler extends IInviteEventHandler, ISubjectEventHandler, IMemberEventHandler, IAppAccessEventHandler, ILicenseEventHandler {
+    /**
+     * Called for any event that doesn't have a specific handler
+     */
+    onUnhandledEvent?(event: unknown): Promise<void> | void;
+}
+/**
+ * Base class for invite event handlers
+ * Extend this and override only the methods you need
+ *
+ * @example
+ * ```typescript
+ * class MyInviteHandler extends InviteEventHandler {
+ *   async onInviteAccepted(event: InviteAcceptedEvent) {
+ *     await sendWelcomeEmail(event.data.email);
+ *   }
+ * }
+ * ```
+ */
+declare abstract class InviteEventHandler implements IInviteEventHandler {
+    onInviteCreated?(_event: InviteCreatedEvent): Promise<void> | void;
+    onInviteAccepted?(_event: InviteAcceptedEvent): Promise<void> | void;
+    onInviteDeleted?(_event: InviteDeletedEvent): Promise<void> | void;
+    onInviteExpired?(_event: InviteExpiredEvent): Promise<void> | void;
+}
+/**
+ * Base class for subject event handlers (users, service accounts, machines)
+ *
+ * @example
+ * ```typescript
+ * class MySubjectHandler extends SubjectEventHandler {
+ *   async onSubjectCreated(event: SubjectCreatedEvent) {
+ *     // event.data.sub is the subject ID (could be user, service account, etc.)
+ *     await this.db.subjects.create({ id: event.data.sub, email: event.data.email });
+ *   }
+ * }
+ * ```
+ */
+declare abstract class SubjectEventHandler implements ISubjectEventHandler {
+    onSubjectCreated?(_event: SubjectCreatedEvent): Promise<void> | void;
+    onSubjectUpdated?(_event: SubjectUpdatedEvent): Promise<void> | void;
+    onSubjectDeleted?(_event: SubjectDeletedEvent): Promise<void> | void;
+    onSubjectDeactivated?(_event: SubjectDeactivatedEvent): Promise<void> | void;
+}
+/**
+ * Base class for member event handlers
+ */
+declare abstract class MemberEventHandler implements IMemberEventHandler {
+    onMemberJoined?(_event: MemberJoinedEvent): Promise<void> | void;
+    onMemberLeft?(_event: MemberLeftEvent): Promise<void> | void;
+    onMemberRoleChanged?(_event: MemberRoleChangedEvent): Promise<void> | void;
+    onMemberSuspended?(_event: MemberSuspendedEvent): Promise<void> | void;
+    onMemberActivated?(_event: MemberActivatedEvent): Promise<void> | void;
+}
+/**
+ * Base class for app access event handlers
+ */
+declare abstract class AppAccessEventHandler implements IAppAccessEventHandler {
+    onAppAccessGranted?(_event: AppAccessGrantedEvent): Promise<void> | void;
+    onAppAccessRevoked?(_event: AppAccessRevokedEvent): Promise<void> | void;
+    /**
+     * @deprecated Use onAppAccessRevoked instead. This method exists for backwards compatibility.
+     */
+    onAppAccessDeactivated?(event: AppAccessRevokedEvent): Promise<void> | void;
+    onAppAccessRoleChanged?(_event: AppAccessRoleChangedEvent): Promise<void> | void;
+}
+/**
+ * Base class for license event handlers
+ */
+declare abstract class LicenseEventHandler implements ILicenseEventHandler {
+    onLicenseAssigned?(_event: LicenseAssignedEvent): Promise<void> | void;
+    onLicenseRevoked?(_event: LicenseRevokedEvent): Promise<void> | void;
+    onLicenseChanged?(_event: LicenseChangedEvent): Promise<void> | void;
+}
+/**
+ * Base class for handling ALL events
+ * Extend this and override only the methods you need
+ *
+ * @example
+ * ```typescript
+ * class MyEventHandler extends AuthVitalEventHandler {
+ *   async onSubjectCreated(event: SubjectCreatedEvent) {
+ *     // event.data.sub is the subject ID
+ *     await this.db.subjects.create({ id: event.data.sub, email: event.data.email });
+ *   }
+ *
+ *   async onMemberJoined(event: MemberJoinedEvent) {
+ *     await this.slack.notify(`${event.data.email} joined!`);
+ *   }
+ *
+ *   onUnhandledEvent(event: unknown) {
+ *     console.log('Unhandled:', event);
+ *   }
+ * }
+ * ```
+ */
+declare abstract class AuthVitalEventHandler implements IAuthVitalEventHandler {
+    onInviteCreated?(_event: InviteCreatedEvent): Promise<void> | void;
+    onInviteAccepted?(_event: InviteAcceptedEvent): Promise<void> | void;
+    onInviteDeleted?(_event: InviteDeletedEvent): Promise<void> | void;
+    onInviteExpired?(_event: InviteExpiredEvent): Promise<void> | void;
+    onSubjectCreated?(_event: SubjectCreatedEvent): Promise<void> | void;
+    onSubjectUpdated?(_event: SubjectUpdatedEvent): Promise<void> | void;
+    onSubjectDeleted?(_event: SubjectDeletedEvent): Promise<void> | void;
+    onSubjectDeactivated?(_event: SubjectDeactivatedEvent): Promise<void> | void;
+    onMemberJoined?(_event: MemberJoinedEvent): Promise<void> | void;
+    onMemberLeft?(_event: MemberLeftEvent): Promise<void> | void;
+    onMemberRoleChanged?(_event: MemberRoleChangedEvent): Promise<void> | void;
+    onMemberSuspended?(_event: MemberSuspendedEvent): Promise<void> | void;
+    onMemberActivated?(_event: MemberActivatedEvent): Promise<void> | void;
+    onAppAccessGranted?(_event: AppAccessGrantedEvent): Promise<void> | void;
+    onAppAccessRevoked?(_event: AppAccessRevokedEvent): Promise<void> | void;
+    /**
+     * @deprecated Use onAppAccessRevoked instead. This method exists for backwards compatibility.
+     */
+    onAppAccessDeactivated?(event: AppAccessRevokedEvent): Promise<void> | void;
+    onAppAccessRoleChanged?(_event: AppAccessRoleChangedEvent): Promise<void> | void;
+    onLicenseAssigned?(_event: LicenseAssignedEvent): Promise<void> | void;
+    onLicenseRevoked?(_event: LicenseRevokedEvent): Promise<void> | void;
+    onLicenseChanged?(_event: LicenseChangedEvent): Promise<void> | void;
+    onUnhandledEvent?(_event: unknown): Promise<void> | void;
+}
+
+interface WebhookHeaders {
+    'x-authvital-signature'?: string;
+    'x-authvital-key-id'?: string;
+    'x-authvital-timestamp'?: string;
+    'x-authvital-event-id'?: string;
+    'x-authvital-event-type'?: string;
+}
+interface WebhookHandlerOptions {
+    /**
+     * URL to the AuthVital JWKS endpoint
+     * Example: 'https://auth.example.com/.well-known/jwks.json'
+     */
+    jwksUrl: string;
+    /**
+     * Maximum age of the timestamp in seconds (default: 300 = 5 minutes)
+     * Prevents replay attacks with old signatures
+     */
+    maxTimestampAge?: number;
+    /**
+     * Cache TTL for JWKS keys in milliseconds (default: 3600000 = 1 hour)
+     */
+    keysCacheTtl?: number;
+}
+/**
+ * Low-level webhook signature verifier
+ *
+ * For most use cases, use WebhookRouter + AuthVitalEventHandler instead.
+ * This class is useful for advanced scenarios where you need full control
+ * over event parsing and routing.
+ *
+ * @example
+ * ```typescript
+ * const verifier = new AuthVitalWebhooks({
+ *   jwksUrl: 'https://auth.example.com/.well-known/jwks.json'
+ * });
+ *
+ * app.post('/webhooks', async (req, res) => {
+ *   try {
+ *     const event = await verifier.verifyAndParse(req.body, req.headers);
+ *     // Handle event manually...
+ *     res.status(200).send('OK');
+ *   } catch (err) {
+ *     res.status(400).send('Invalid webhook');
+ *   }
+ * });
+ * ```
+ */
+declare class AuthVitalWebhooks {
+    private readonly jwksUrl;
+    private readonly maxTimestampAge;
+    private readonly keysCacheTtl;
+    private keysCache;
+    private keysCacheExpiry;
+    constructor(options: WebhookHandlerOptions);
+    /**
+     * Verify and parse a webhook payload
+     *
+     * @param body - The raw request body (string or object)
+     * @param headers - The request headers (can pass full headers object)
+     * @returns The parsed and verified event
+     * @throws Error if verification fails
+     */
+    verifyAndParse(body: string | object, headers: WebhookHeaders | Record<string, string | string[] | undefined>): Promise<SyncEvent>;
+    /**
+     * Verify signature only (without parsing)
+     * Useful if you want to handle parsing yourself
+     */
+    verify(body: string | object, signature: string, keyId: string, timestamp: string): Promise<boolean>;
+    /**
+     * Get a public key from the JWKS endpoint
+     */
+    private getPublicKey;
+    /**
+     * Normalize headers to lowercase keys and string values
+     */
+    private normalizeHeaders;
+    /**
+     * Clear the key cache (useful for testing or key rotation)
+     */
+    clearCache(): void;
+}
+
+interface WebhookRouterOptions {
+    /**
+     * AuthVital base URL (from AV_HOST env var)
+     * Example: 'https://auth.example.com'
+     * JWKS endpoint is automatically derived as: {authVitalHost}/.well-known/jwks.json
+     */
+    authVitalHost?: string;
+    /**
+     * Event handler instance - extend AuthVitalEventHandler and implement methods
+     */
+    handler: IAuthVitalEventHandler;
+    /**
+     * Maximum age of the timestamp in seconds (default: 300 = 5 minutes)
+     * Prevents replay attacks with old signatures
+     */
+    maxTimestampAge?: number;
+    /**
+     * Cache TTL for JWKS keys in milliseconds (default: 3600000 = 1 hour)
+     */
+    keysCacheTtl?: number;
+}
+/**
+ * WebhookRouter - Routes verified webhook events to handler methods
+ *
+ * @example
+ * ```typescript
+ * // 1. Create your handler by extending the base class
+ * class MyHandler extends AuthVitalEventHandler {
+ *   constructor(private db: Database, private slack: SlackClient) {
+ *     super();
+ *   }
+ *
+ *   async onSubjectCreated(event: SubjectCreatedEvent) {
+ *     // event.data.sub is the subject ID (user, service account, etc.)
+ *     await this.db.subjects.create({
+ *       id: event.data.sub,
+ *       email: event.data.email,
+ *       type: event.data.subject_type,
+ *     });
+ *   }
+ *
+ *   async onMemberJoined(event: MemberJoinedEvent) {
+ *     await this.slack.send(`Welcome ${event.data.email}!`);
+ *   }
+ * }
+ *
+ * // 2. Create the router (AV_HOST is read from environment automatically)
+ * const router = new WebhookRouter({
+ *   handler: new MyHandler(db, slack),
+ * });
+ *
+ * // 3. Use in your Express app
+ * app.post('/webhooks/authvital', router.expressHandler());
+ * ```
+ */
+declare class WebhookRouter {
+    private readonly verifier;
+    private readonly handler;
+    constructor(options: WebhookRouterOptions);
+    /**
+     * Handle a webhook request
+     */
+    handle(body: string | object, headers: WebhookHeaders | Record<string, string | string[] | undefined>): Promise<{
+        status: number;
+        body: {
+            success: boolean;
+            message?: string;
+            error?: string;
+        };
+    }>;
+    /**
+     * Dispatch event to the appropriate handler method
+     */
+    private dispatch;
+    /**
+     * Express middleware handler
+     */
+    expressHandler(): (req: any, res: any) => Promise<void>;
+    /**
+     * Get the underlying verifier
+     */
+    getVerifier(): AuthVitalWebhooks;
+}
+
+export { type AppAccessGrantedEvent as A, SubjectEventHandler as B, MemberEventHandler as C, AppAccessEventHandler as D, LicenseEventHandler as E, type IAuthVitalEventHandler as F, type IInviteEventHandler as G, type ISubjectEventHandler as H, type InviteCreatedEvent as I, type IMemberEventHandler as J, type IAppAccessEventHandler as K, type LicenseAssignedEvent as L, type MemberJoinedEvent as M, type ILicenseEventHandler as N, type WebhookRouterOptions as O, AuthVitalWebhooks as P, type WebhookHandlerOptions as Q, type SyncEvent as S, WebhookRouter as W, type SyncEventType as a, type InviteAcceptedEvent as b, type InviteDeletedEvent as c, type InviteExpiredEvent as d, type SubjectData as e, type SubjectCreatedEvent as f, type SubjectUpdatedEvent as g, type SubjectDeletedEvent as h, type SubjectDeactivatedEvent as i, type MemberLeftEvent as j, type MemberRoleChangedEvent as k, type MemberSuspendedEvent as l, type MemberActivatedEvent as m, type AppAccessRevokedEvent as n, type AppAccessDeactivatedEvent as o, type AppAccessRoleChangedEvent as p, type LicenseRevokedEvent as q, type LicenseChangedEvent as r, isInviteEvent as s, isSubjectEvent as t, isMemberEvent as u, isAppAccessEvent as v, isLicenseEvent as w, SYNC_EVENT_TYPES as x, AuthVitalEventHandler as y, InviteEventHandler as z };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "authvital-sdk",
+  "version": "0.1.1-dev.3.cefb119.0",
+  "description": "AuthVital authentication SDK for React and Node.js applications",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.mjs",
+      "require": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "react",
+    "auth",
+    "oauth",
+    "authentication",
+    "authvital",
+    "identity",
+    "idp",
+    "multi-tenant",
+    "saas"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/intersparkio/authvital",
+    "directory": "backend/sdk"
+  },
+  "homepage": "https://github.com/intersparkio/authvital#readme",
+  "bugs": {
+    "url": "https://github.com/intersparkio/authvital/issues"
+  }
+}