@gzl10/nexus-plugin-pocketid 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,296 @@
+import { ConfigEntityDefinition, ModuleManifest, OidcState, ActionEntityDefinition, CollectionEntityDefinition, EventEntityDefinition, PluginManifest } from '@gzl10/nexus-sdk';
+export { IdTokenClaims, OidcClient, OidcDiscoveryDocument, OidcTokens, OidcUserInfo, createOidcClient, getOidcClient } from '@gzl10/nexus-sdk';
+
+/**
+ * PocketID Configuration Types
+ */
+/**
+ * PocketID config stored in database
+ */
+interface PocketIdConfig {
+    /** Enable/disable PocketID authentication */
+    enabled: boolean;
+    /** PocketID issuer URL (e.g., https://auth.example.com) */
+    issuer_url: string;
+    /** OIDC Client ID */
+    client_id: string;
+    /** OIDC Client Secret (encrypted) */
+    client_secret: string;
+    /** Scopes to request (default: openid profile email) */
+    scopes: string;
+    /** Auto-register new users */
+    auto_register: boolean;
+    /** Allowed email domains (JSON array, optional) */
+    allowed_domains: string | null;
+    /** Default role for new users */
+    default_role: string | null;
+}
+/**
+ * Config service interface
+ */
+interface ConfigService {
+    /** Get current config */
+    getConfig(): Promise<PocketIdConfig | null>;
+    /** Check if PocketID is enabled */
+    isEnabled(): Promise<boolean>;
+}
+
+/**
+ * PocketID Config Entity
+ *
+ * Stores OIDC configuration for PocketID authentication
+ */
+declare const pocketIdConfigEntity: ConfigEntityDefinition;
+
+declare function getConfigService(): ConfigService;
+declare function setConfigService(service: ConfigService): void;
+/**
+ * PocketID Config Module
+ */
+declare const configModule: ModuleManifest;
+
+/**
+ * PocketID Auth Types
+ */
+
+/**
+ * Session result after successful authentication
+ */
+interface SessionResult {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    user: {
+        id: string;
+        email: string;
+        name?: string;
+    };
+    /** Frontend URL to redirect user after auth (server-side flow) */
+    returnUrl?: string;
+}
+/**
+ * PocketID-specific OIDC state (extends base)
+ */
+interface PocketIdState extends OidcState {
+    /** User ID if linking account */
+    linkUserId?: string;
+    /** Frontend URL to redirect user after auth completes */
+    returnUrl?: string;
+}
+/**
+ * Auth service interface
+ */
+interface PocketIdAuthService {
+    /** Generate authorization URL and state */
+    getAuthorizationUrl(redirectUri: string, linkUserId?: string, returnUrl?: string): Promise<{
+        url: string;
+        state: string;
+    }>;
+    /** Handle callback from PocketID */
+    handleCallback(code: string, state: string): Promise<SessionResult>;
+    /** Verify state is valid */
+    verifyState(state: string): Promise<PocketIdState | null>;
+    /** Clear state after use */
+    clearState(state: string): Promise<void>;
+}
+
+declare function getAuthService(): PocketIdAuthService;
+declare function setAuthService(service: PocketIdAuthService): void;
+
+/**
+ * PocketID Auth Controller
+ *
+ * Handles OIDC endpoints:
+ * - GET /pocketid_auth/authorize - Start OIDC flow
+ * - GET /pocketid_auth/callback - Handle OIDC callback (from PocketID redirect)
+ * - GET /pocketid_auth/link - Link existing account (requires auth)
+ * - GET /pocketid_auth/status - Check if PocketID is linked
+ */
+
+declare const authActions: ActionEntityDefinition[];
+
+/**
+ * PocketID Auth Module
+ *
+ * Provides OIDC authentication endpoints:
+ * - GET /pocketid/authorize - Start auth flow
+ * - GET /pocketid/callback - Handle callback
+ * - GET /pocketid/link - Link existing account
+ * - GET /pocketid/status - Check link status
+ */
+declare const authModule: ModuleManifest;
+
+/**
+ * SCIM Entity Definitions
+ *
+ * - scim_config: SCIM server configuration (token, behavior)
+ * - scim_users: SCIM-provisioned user mappings
+ * - scim_groups: SCIM group-to-role mappings
+ * - scim_log: Audit log of SCIM operations
+ */
+
+declare const scimConfigEntity: ConfigEntityDefinition;
+declare const scimUsersEntity: CollectionEntityDefinition;
+declare const scimGroupsEntity: CollectionEntityDefinition;
+declare const scimLogEntity: EventEntityDefinition;
+
+/**
+ * SCIM 2.0 Protocol Types (RFC 7643/7644)
+ *
+ * Types for the SCIM server that receives provisioning
+ * requests from PocketID.
+ */
+interface ScimMeta {
+    resourceType: string;
+    created?: string;
+    lastModified?: string;
+    location?: string;
+}
+interface ScimUserName {
+    formatted?: string;
+    familyName?: string;
+    givenName?: string;
+}
+interface ScimUserEmail {
+    value: string;
+    type?: string;
+    primary?: boolean;
+}
+interface ScimUser {
+    schemas: string[];
+    id?: string;
+    externalId?: string;
+    userName: string;
+    name?: ScimUserName;
+    displayName?: string;
+    emails?: ScimUserEmail[];
+    active?: boolean;
+    meta?: ScimMeta;
+}
+interface ScimGroupMember {
+    value: string;
+    display?: string;
+    $ref?: string;
+}
+interface ScimGroup {
+    schemas: string[];
+    id?: string;
+    externalId?: string;
+    displayName: string;
+    members?: ScimGroupMember[];
+    meta?: ScimMeta;
+}
+interface ScimListResponse<T = ScimUser | ScimGroup> {
+    schemas: ['urn:ietf:params:scim:api:messages:2.0:ListResponse'];
+    totalResults: number;
+    startIndex: number;
+    itemsPerPage: number;
+    Resources: T[];
+}
+interface ScimPatchOp {
+    op: 'add' | 'remove' | 'replace';
+    path?: string;
+    value?: unknown;
+}
+/** SCIM user stored in pocketid_scim_users */
+interface ScimUserRecord {
+    id: string;
+    scim_id: string;
+    user_id: string;
+    scim_username: string;
+    scim_email: string | null;
+    scim_display_name: string | null;
+    active: boolean;
+    scim_payload: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** SCIM group stored in pocketid_scim_groups */
+interface ScimGroupRecord {
+    id: string;
+    scim_id: string;
+    display_name: string;
+    nexus_role: string;
+    created_at: string;
+    updated_at: string;
+}
+/** SCIM sync log entry */
+interface ScimLogEntry {
+    id: string;
+    operation: 'CREATE' | 'UPDATE' | 'DELETE';
+    resource_type: 'User' | 'Group';
+    scim_id: string;
+    nexus_id: string | null;
+    status: 'success' | 'error';
+    error_message: string | null;
+    created_at: string;
+}
+/** SCIM service interface */
+interface ScimService {
+    getUser(scimId: string): Promise<ScimUser | null>;
+    listUsers(filter?: string, startIndex?: number, count?: number): Promise<ScimListResponse<ScimUser>>;
+    createUser(user: ScimUser): Promise<ScimUser>;
+    replaceUser(scimId: string, user: ScimUser): Promise<ScimUser>;
+    patchUser(scimId: string, ops: ScimPatchOp[]): Promise<ScimUser>;
+    deleteUser(scimId: string): Promise<void>;
+    getGroup(scimId: string): Promise<ScimGroup | null>;
+    listGroups(filter?: string, startIndex?: number, count?: number): Promise<ScimListResponse<ScimGroup>>;
+    createGroup(group: ScimGroup): Promise<ScimGroup>;
+    replaceGroup(scimId: string, group: ScimGroup): Promise<ScimGroup>;
+    patchGroup(scimId: string, ops: ScimPatchOp[]): Promise<ScimGroup>;
+    deleteGroup(scimId: string): Promise<void>;
+}
+/** SCIM config stored in database */
+interface ScimConfig {
+    enabled: boolean;
+    token: string;
+    auto_create_users: boolean;
+    default_role: string;
+    sync_groups: boolean;
+    deprovisioning_action: 'deactivate' | 'delete';
+}
+
+/**
+ * SCIM Provisioning Service
+ *
+ * Handles SCIM 2.0 operations mapping PocketID users/groups
+ * to Nexus users and roles.
+ */
+
+declare function getScimService(): ScimService;
+declare function setScimService(service: ScimService): void;
+
+/**
+ * PocketID SCIM Module
+ *
+ * Provides a SCIM 2.0 server for user/group provisioning from PocketID.
+ * PocketID pushes user and group changes to our SCIM endpoints.
+ *
+ * Endpoints mounted at: /api/v1/pocketid/scim/
+ */
+declare const scimModule: ModuleManifest;
+
+/**
+ * PocketID Plugin for Nexus.
+ *
+ * Provides OIDC authentication with PocketID for passwordless passkey login.
+ *
+ * Features:
+ * - OIDC Authorization Code Flow
+ * - User auto-registration or linking
+ * - Passkey-based authentication via PocketID
+ * - Domain allowlist support
+ *
+ * @example
+ * ```typescript
+ * import { createNexus } from '@gzl10/nexus-backend'
+ * import { pocketIdPlugin } from '@gzl10/nexus-plugin-pocketid'
+ *
+ * const nexus = createNexus({
+ *   plugins: [pocketIdPlugin]
+ * })
+ * ```
+ */
+declare const pocketIdPlugin: PluginManifest;
+
+export { type ConfigService, type PocketIdAuthService, type PocketIdConfig, type PocketIdState, type ScimConfig, type ScimGroup, type ScimGroupRecord, type ScimLogEntry, type ScimService, type ScimUser, type ScimUserRecord, type SessionResult, authActions, authModule, configModule, pocketIdPlugin as default, getAuthService, getConfigService, getScimService, pocketIdConfigEntity, pocketIdPlugin, scimConfigEntity, scimGroupsEntity, scimLogEntity, scimModule, scimUsersEntity, setAuthService, setConfigService, setScimService };