@checkstack/auth-common 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,114 @@
+# @checkstack/auth-common
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/common@0.0.2
+
+## 0.2.1
+
+### Patch Changes
+
+- a65e002: Add compile-time type safety for Lucide icon names
+
+  - Add `LucideIconName` type and `lucideIconSchema` Zod schema to `@checkstack/common`
+  - Update backend interfaces (`AuthStrategy`, `NotificationStrategy`, `IntegrationProvider`, `CommandDefinition`) to use `LucideIconName`
+  - Update RPC contracts to use `lucideIconSchema` for proper type inference across RPC boundaries
+  - Simplify `SocialProviderButton` to use `DynamicIcon` directly (removes 30+ lines of pascalCase conversion)
+  - Replace static `iconMap` in `SearchDialog` with `DynamicIcon` for dynamic icon rendering
+  - Add fallback handling in `DynamicIcon` when icon name isn't found
+  - Fix legacy kebab-case icon names to PascalCase: `mail`→`Mail`, `send`→`Send`, `github`→`Github`, `key-round`→`KeyRound`, `network`→`Network`, `AlertCircle`→`CircleAlert`
+
+- Updated dependencies [a65e002]
+  - @checkstack/common@0.2.0
+
+## 0.2.0
+
+### Minor Changes
+
+- e26c08e: Add password change functionality for credential-authenticated users
+
+  - Add `changePassword` route to auth-common
+  - Create `ChangePasswordPage.tsx` component with password validation, current password verification, and session revocation option
+  - Add "Change Password" menu item in User Menu
+  - Reuses patterns from existing password reset flow for consistency
+
+## 0.1.0
+
+### Minor Changes
+
+- 32f2535: Refactor application role assignment
+
+  - Removed role selection from the application creation dialog
+  - New applications now automatically receive the "Applications" role
+  - Roles are now manageable inline in the Applications table (similar to user role management)
+  - Added informational alert in create dialog explaining default role behavior
+
+- b354ab3: # Strategy Instructions Support & Telegram Notification Plugin
+
+  ## Strategy Instructions Interface
+
+  Added `adminInstructions` and `userInstructions` optional fields to the `NotificationStrategy` interface. These allow strategies to export markdown-formatted setup guides that are displayed in the configuration UI:
+
+  - **`adminInstructions`**: Shown when admins configure platform-wide strategy settings (e.g., how to create API keys)
+  - **`userInstructions`**: Shown when users configure their personal settings (e.g., how to link their account)
+
+  ### Updated Components
+
+  - `StrategyConfigCard` now accepts an `instructions` prop and renders it before config sections
+  - `StrategyCard` passes `adminInstructions` to `StrategyConfigCard`
+  - `UserChannelCard` renders `userInstructions` when users need to connect
+
+  ## New Telegram Notification Plugin
+
+  Added `@checkstack/notification-telegram-backend` plugin for sending notifications via Telegram:
+
+  - Uses [grammY](https://grammy.dev/) framework for Telegram Bot API integration
+  - Sends messages with MarkdownV2 formatting and inline keyboard buttons for actions
+  - Includes comprehensive admin instructions for bot setup via @BotFather
+  - Includes user instructions for account linking
+
+  ### Configuration
+
+  Admins need to configure a Telegram Bot Token obtained from @BotFather.
+
+  ### User Linking
+
+  The strategy uses `contactResolution: { type: "custom" }` for Telegram Login Widget integration. Full frontend integration for the Login Widget is pending future work.
+
+### Patch Changes
+
+- ffc28f6: ### Anonymous Role and Public Access
+
+  Introduces a configurable "anonymous" role for managing permissions available to unauthenticated users.
+
+  **Core Changes:**
+
+  - Added `userType: "public"` - endpoints accessible by both authenticated users (with their permissions) and anonymous users (with anonymous role permissions)
+  - Renamed `userType: "both"` to `"authenticated"` for clarity
+  - Renamed `isDefault` to `isAuthenticatedDefault` on Permission interface
+  - Added `isPublicDefault` flag for permissions that should be granted to the anonymous role by default
+
+  **Backend Infrastructure:**
+
+  - New `anonymous` system role created during auth-backend initialization
+  - New `disabled_public_default_permission` table tracks admin-disabled public defaults
+  - `autoAuthMiddleware` now checks anonymous role permissions for unauthenticated public endpoint access
+  - `AuthService.getAnonymousPermissions()` with 1-minute caching for performance
+  - Anonymous role filtered from `getRoles` endpoint (not assignable to users)
+  - Validation prevents assigning anonymous role to users
+
+  **Catalog Integration:**
+
+  - `catalog.read` permission now has both `isAuthenticatedDefault` and `isPublicDefault`
+  - Read endpoints (`getSystems`, `getGroups`, `getEntities`) now use `userType: "public"`
+
+  **UI:**
+
+  - New `PermissionGate` component for conditionally rendering content based on permissions
+
+- Updated dependencies [ffc28f6]
+  - @checkstack/common@0.1.0

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@checkstack/auth-common",
+  "version": "0.0.2",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "workspace:*",
+    "@orpc/contract": "^1.13.2",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "workspace:*",
+    "typescript": "^5.7.2",
+    "@checkstack/scripts": "workspace:*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./permissions";
+export * from "./rpc-contract";
+export * from "./plugin-metadata";
+export * from "./schemas";
+export { authRoutes } from "./routes";

package/src/permissions.ts

@@ -0,0 +1,50 @@
+import type { Permission } from "@checkstack/common";
+
+export const permissions = {
+  usersRead: {
+    id: "users.read",
+    description: "List all users",
+  },
+  usersCreate: {
+    id: "users.create",
+    description: "Create new users (credential strategy)",
+  },
+  usersManage: {
+    id: "users.manage",
+    description: "Delete users",
+  },
+  rolesRead: {
+    id: "roles.read",
+    description: "Read and list roles",
+  },
+  rolesCreate: {
+    id: "roles.create",
+    description: "Create new roles",
+  },
+  rolesUpdate: {
+    id: "roles.update",
+    description: "Update role names and permissions",
+  },
+  rolesDelete: {
+    id: "roles.delete",
+    description: "Delete roles",
+  },
+  rolesManage: {
+    id: "roles.manage",
+    description: "Assign roles to users",
+  },
+  strategiesManage: {
+    id: "strategies.manage",
+    description: "Manage authentication strategies and settings",
+  },
+  registrationManage: {
+    id: "registration.manage",
+    description: "Manage user registration settings",
+  },
+  applicationsManage: {
+    id: "applications.manage",
+    description: "Create, update, delete, and view external applications",
+  },
+} satisfies Record<string, Permission>;
+
+export const permissionList = Object.values(permissions);

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the auth plugin.
+ * Exported from the common package so both backend and frontend can reference it.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "auth",
+});

package/src/routes.ts

@@ -0,0 +1,14 @@
+import { createRoutes } from "@checkstack/common";
+
+/**
+ * Route definitions for the auth plugin.
+ */
+export const authRoutes = createRoutes("auth", {
+  login: "/login",
+  register: "/register",
+  error: "/error",
+  settings: "/settings",
+  forgotPassword: "/forgot-password",
+  resetPassword: "/reset-password",
+  changePassword: "/change-password",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,395 @@
+import { oc } from "@orpc/contract";
+import {
+  createClientDefinition,
+  type ProcedureMetadata,
+  lucideIconSchema,
+} from "@checkstack/common";
+import { z } from "zod";
+import { permissions } from "./permissions";
+import { pluginMetadata } from "./plugin-metadata";
+
+// Base builder with full metadata support
+const _base = oc.$meta<ProcedureMetadata>({});
+
+// Zod schemas for return types
+const UserDtoSchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  name: z.string(),
+  roles: z.array(z.string()),
+});
+
+const RoleDtoSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().optional().nullable(),
+  permissions: z.array(z.string()),
+  isSystem: z.boolean().optional(),
+  isAssignable: z.boolean().optional(), // False for anonymous role
+});
+
+const PermissionDtoSchema = z.object({
+  id: z.string(),
+  description: z.string().optional(),
+});
+
+const StrategyDtoSchema = z.object({
+  id: z.string(),
+  displayName: z.string(),
+  description: z.string().optional(),
+  icon: lucideIconSchema.optional(),
+  enabled: z.boolean(),
+  configVersion: z.number(),
+  configSchema: z.record(z.string(), z.unknown()), // JSON Schema representation
+  config: z.record(z.string(), z.unknown()).optional(), // VersionedConfig.data (secrets redacted)
+  adminInstructions: z.string().optional(), // Markdown instructions for admins
+});
+
+const EnabledStrategyDtoSchema = z.object({
+  id: z.string(),
+  displayName: z.string(),
+  description: z.string().optional(),
+  type: z.enum(["credential", "social"]),
+  icon: lucideIconSchema.optional(),
+  requiresManualRegistration: z.boolean(),
+});
+
+const RegistrationStatusSchema = z.object({
+  allowRegistration: z.boolean(),
+});
+
+// ==========================================================================
+// SERVICE-TO-SERVICE SCHEMAS (for auth provider plugins like LDAP)
+// ==========================================================================
+
+const FindUserByEmailInputSchema = z.object({
+  email: z.string().email(),
+});
+
+const FindUserByEmailOutputSchema = z
+  .object({
+    id: z.string(),
+  })
+  .optional();
+
+const UpsertExternalUserInputSchema = z.object({
+  email: z.string().email(),
+  name: z.string(),
+  providerId: z.string(), // e.g., "ldap"
+  accountId: z.string(), // Provider-specific account ID (e.g., LDAP username)
+  password: z.string(), // Hashed password
+  autoUpdateUser: z.boolean().optional(), // Update existing user's name
+});
+
+const UpsertExternalUserOutputSchema = z.object({
+  userId: z.string(),
+  created: z.boolean(), // true if new user was created, false if existing
+});
+
+const CreateSessionInputSchema = z.object({
+  userId: z.string(),
+  token: z.string(),
+  expiresAt: z.coerce.date(),
+});
+
+const CreateCredentialUserInputSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1),
+  password: z.string(), // Validated against passwordSchema on backend
+});
+
+const CreateCredentialUserOutputSchema = z.object({
+  userId: z.string(),
+});
+
+// Auth RPC Contract with full metadata
+export const authContract = {
+  // ==========================================================================
+  // ANONYMOUS ENDPOINTS (userType: "anonymous")
+  // These can be called without authentication (login/registration pages)
+  // ==========================================================================
+
+  getEnabledStrategies: _base
+    .meta({ userType: "anonymous" })
+    .output(z.array(EnabledStrategyDtoSchema)),
+
+  getRegistrationStatus: _base
+    .meta({ userType: "anonymous" })
+    .output(RegistrationStatusSchema),
+
+  // ==========================================================================
+  // AUTHENTICATED ENDPOINTS (userType: "authenticated" - no specific permission)
+  // ==========================================================================
+
+  permissions: _base
+    .meta({ userType: "authenticated" }) // Any authenticated user can check their own permissions
+    .output(z.object({ permissions: z.array(z.string()) })),
+
+  // ==========================================================================
+  // USER MANAGEMENT (userType: "user" with permissions)
+  // ==========================================================================
+
+  getUsers: _base
+    .meta({ userType: "user", permissions: [permissions.usersRead.id] })
+    .output(z.array(UserDtoSchema)),
+
+  deleteUser: _base
+    .meta({ userType: "user", permissions: [permissions.usersManage.id] })
+    .input(z.string())
+    .output(z.void()),
+
+  createCredentialUser: _base
+    .meta({ userType: "user", permissions: [permissions.usersCreate.id] })
+    .input(CreateCredentialUserInputSchema)
+    .output(CreateCredentialUserOutputSchema),
+
+  updateUserRoles: _base
+    .meta({ userType: "user", permissions: [permissions.usersManage.id] })
+    .input(
+      z.object({
+        userId: z.string(),
+        roles: z.array(z.string()),
+      })
+    )
+    .output(z.void()),
+
+  // ==========================================================================
+  // ROLE MANAGEMENT (userType: "user" with permissions)
+  // ==========================================================================
+
+  getRoles: _base
+    .meta({ userType: "user", permissions: [permissions.rolesRead.id] })
+    .output(z.array(RoleDtoSchema)),
+
+  getPermissions: _base
+    .meta({ userType: "user", permissions: [permissions.rolesRead.id] })
+    .output(z.array(PermissionDtoSchema)),
+
+  createRole: _base
+    .meta({ userType: "user", permissions: [permissions.rolesCreate.id] })
+    .input(
+      z.object({
+        name: z.string(),
+        description: z.string().optional(),
+        permissions: z.array(z.string()),
+      })
+    )
+    .output(z.void()),
+
+  updateRole: _base
+    .meta({ userType: "user", permissions: [permissions.rolesUpdate.id] })
+    .input(
+      z.object({
+        id: z.string(),
+        name: z.string().optional(),
+        description: z.string().optional(),
+        permissions: z.array(z.string()),
+      })
+    )
+    .output(z.void()),
+
+  deleteRole: _base
+    .meta({ userType: "user", permissions: [permissions.rolesDelete.id] })
+    .input(z.string())
+    .output(z.void()),
+
+  // ==========================================================================
+  // STRATEGY MANAGEMENT (userType: "user" with permissions)
+  // ==========================================================================
+
+  getStrategies: _base
+    .meta({ userType: "user", permissions: [permissions.strategiesManage.id] })
+    .output(z.array(StrategyDtoSchema)),
+
+  updateStrategy: _base
+    .meta({ userType: "user", permissions: [permissions.strategiesManage.id] })
+    .input(
+      z.object({
+        id: z.string(),
+        enabled: z.boolean(),
+        config: z.record(z.string(), z.unknown()).optional(),
+      })
+    )
+    .output(z.object({ success: z.boolean() })),
+
+  reloadAuth: _base
+    .meta({ userType: "user", permissions: [permissions.strategiesManage.id] })
+    .output(z.object({ success: z.boolean() })),
+
+  // ==========================================================================
+  // REGISTRATION MANAGEMENT (userType: "user" with permissions)
+  // ==========================================================================
+
+  getRegistrationSchema: _base
+    .meta({
+      userType: "user",
+      permissions: [permissions.registrationManage.id],
+    })
+    .output(z.record(z.string(), z.unknown())),
+
+  setRegistrationStatus: _base
+    .meta({
+      userType: "user",
+      permissions: [permissions.registrationManage.id],
+    })
+    .input(RegistrationStatusSchema)
+    .output(z.object({ success: z.boolean() })),
+
+  // ==========================================================================
+  // INTERNAL SERVICE ENDPOINTS (userType: "service")
+  // ==========================================================================
+
+  /**
+   * Get permissions assigned to the anonymous role.
+   * Used by core AuthService for permission checks on public endpoints.
+   */
+  getAnonymousPermissions: _base
+    .meta({ userType: "service" })
+    .output(z.array(z.string())),
+
+  /**
+   * Find a user by email address.
+   * Used by external auth providers (e.g., LDAP) to check if a user exists.
+   */
+  findUserByEmail: _base
+    .meta({ userType: "service" })
+    .input(FindUserByEmailInputSchema)
+    .output(FindUserByEmailOutputSchema),
+
+  /**
+   * Upsert a user from an external auth provider.
+   * Creates user + account if new, or updates user if autoUpdateUser is true.
+   * Used by external auth providers (e.g., LDAP) to sync users.
+   */
+  upsertExternalUser: _base
+    .meta({ userType: "service" })
+    .input(UpsertExternalUserInputSchema)
+    .output(UpsertExternalUserOutputSchema),
+
+  /**
+   * Create a session for a user.
+   * Used by external auth providers (e.g., LDAP) after successful authentication.
+   */
+  createSession: _base
+    .meta({ userType: "service" })
+    .input(CreateSessionInputSchema)
+    .output(z.object({ sessionId: z.string() })),
+
+  /**
+   * Get a user by their ID.
+   * Used by notification backend to fetch user email for contact resolution.
+   */
+  getUserById: _base
+    .meta({ userType: "service" })
+    .input(z.object({ userId: z.string() }))
+    .output(
+      z
+        .object({
+          id: z.string(),
+          email: z.string(),
+          name: z.string().nullable(),
+        })
+        .optional()
+    ),
+
+  /**
+   * Filter a list of user IDs to only those who have a specific permission.
+   * Used by SignalService to send signals only to authorized users.
+   */
+  filterUsersByPermission: _base
+    .meta({ userType: "service" })
+    .input(
+      z.object({
+        userIds: z.array(z.string()),
+        permission: z.string(), // Fully-qualified permission ID
+      })
+    )
+    .output(z.array(z.string())), // Returns filtered user IDs
+
+  // ==========================================================================
+  // APPLICATION MANAGEMENT (userType: "user" with permissions)
+  // External API applications (API keys) with RBAC integration
+  // ==========================================================================
+
+  getApplications: _base
+    .meta({
+      userType: "user",
+      permissions: [permissions.applicationsManage.id],
+    })
+    .output(
+      z.array(
+        z.object({
+          id: z.string(),
+          name: z.string(),
+          description: z.string().optional().nullable(),
+          roles: z.array(z.string()),
+          createdById: z.string(),
+          createdAt: z.coerce.date(),
+          lastUsedAt: z.coerce.date().optional().nullable(),
+        })
+      )
+    ),
+
+  createApplication: _base
+    .meta({
+      userType: "user",
+      permissions: [permissions.applicationsManage.id],
+    })
+    .input(
+      z.object({
+        name: z.string().min(1).max(100),
+        description: z.string().max(500).optional(),
+      })
+    )
+    .output(
+      z.object({
+        application: z.object({
+          id: z.string(),
+          name: z.string(),
+          description: z.string().optional().nullable(),
+          roles: z.array(z.string()),
+          createdById: z.string(),
+          createdAt: z.coerce.date(),
+        }),
+        secret: z.string(), // Full secret - ONLY shown once!
+      })
+    ),
+
+  updateApplication: _base
+    .meta({
+      userType: "user",
+      permissions: [permissions.applicationsManage.id],
+    })
+    .input(
+      z.object({
+        id: z.string(),
+        name: z.string().optional(),
+        description: z.string().optional().nullable(),
+        roles: z.array(z.string()).optional(),
+      })
+    )
+    .output(z.void()),
+
+  deleteApplication: _base
+    .meta({
+      userType: "user",
+      permissions: [permissions.applicationsManage.id],
+    })
+    .input(z.string())
+    .output(z.void()),
+
+  regenerateApplicationSecret: _base
+    .meta({
+      userType: "user",
+      permissions: [permissions.applicationsManage.id],
+    })
+    .input(z.string())
+    .output(z.object({ secret: z.string() })), // New secret - shown once
+};
+
+// Export contract type
+export type AuthContract = typeof authContract;
+
+// Export client definition for type-safe forPlugin usage
+// Use: const client = rpcApi.forPlugin(AuthApi);
+export const AuthApi = createClientDefinition(authContract, pluginMetadata);

package/src/schemas.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+
+/**
+ * Password validation schema with security requirements.
+ * Used for both registration and password reset flows.
+ *
+ * Requirements:
+ * - Minimum 8 characters
+ * - At least one uppercase letter
+ * - At least one lowercase letter
+ * - At least one number
+ */
+export const passwordSchema = z
+  .string()
+  .min(8, "Password must be at least 8 characters")
+  .regex(/[A-Z]/, "Password must contain at least one uppercase letter")
+  .regex(/[a-z]/, "Password must contain at least one lowercase letter")
+  .regex(/[0-9]/, "Password must contain at least one number");
+
+export type Password = z.infer<typeof passwordSchema>;

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/common.json",
+  "include": [
+    "src"
+  ]
+}