@simple-auth-kit/cli 1.0.0

package/registry/combos/nestjs-drizzle/shared/src/dto/auth.dto.ts

@@ -0,0 +1,429 @@
+// Swagger-only DTOs: these exist to give @nestjs/swagger a typed shape to generate the OpenAPI
+// schema from. They are NOT wired into `@Body()` as the runtime type (the controller keeps its
+// existing `Record<string, unknown>` + `requireString()` validation, unchanged, to avoid
+// widening this into a class-validator migration with its own behavioral risk) — these are
+// documentation-only, referenced via `@ApiBody({ type: ... })` / `@ApiResponse({ type: ... })`.
+//
+// Every `@ApiProperty` below passes an explicit `type` instead of relying on reflected
+// `design:type` metadata — this repo runs via `tsx` (esbuild), which doesn't reliably emit
+// decorator type metadata the way a full `tsc` build does, and @nestjs/swagger throws a
+// "circular dependency" error at boot trying to reflect an unresolved type otherwise.
+//
+// Anything whose shape depends on how this project scopes administration lives in
+// ./admin.dto.ts instead.
+import { ApiProperty } from "@nestjs/swagger";
+
+export class SignupDto {
+  @ApiProperty({ type: String, example: "alice@example.com" })
+  email!: string;
+
+  @ApiProperty({ type: String, example: "correct-horse-battery-staple" })
+  password!: string;
+
+  @ApiProperty({ type: String, required: false, description: "Unique across the deployment.", example: "Alice" })
+  firstName?: string;
+
+  @ApiProperty({ type: String, required: false, description: "Unique across the deployment.", example: "Nguyen" })
+  lastName?: string;
+
+  @ApiProperty({ type: String, required: false, example: "Alice Nguyen" })
+  displayName?: string;
+
+  @ApiProperty({ type: String, required: false, description: "Unique across the deployment." })
+  phone?: string;
+
+  @ApiProperty({ type: String, required: false, description: "Unique across the deployment." })
+  username?: string;
+}
+
+export class LoginDto {
+  @ApiProperty({ type: String, description: "Email, username, or phone — whichever the account has set.", example: "alice@example.com" })
+  identifier!: string;
+
+  @ApiProperty({ type: String, example: "correct-horse-battery-staple" })
+  password!: string;
+}
+
+export class LoginTwoFactorDto {
+  @ApiProperty({ type: String, description: "Returned by POST /auth/login when the account has 2FA enabled" })
+  challengeToken!: string;
+
+  @ApiProperty({ type: String, description: "6-digit TOTP code, or an unused backup code", example: "123456" })
+  code!: string;
+}
+
+export class RefreshDto {
+  @ApiProperty({ type: String })
+  refreshToken!: string;
+}
+
+export class TwoFactorCodeDto {
+  @ApiProperty({ type: String, example: "123456" })
+  code!: string;
+}
+
+export class ForgotPasswordDto {
+  @ApiProperty({ type: String })
+  email!: string;
+}
+
+export class ResetPasswordDto {
+  @ApiProperty({ type: String, description: "Raw token from the sendPasswordResetEmail hook" })
+  token!: string;
+
+  @ApiProperty({ type: String })
+  newPassword!: string;
+}
+
+export class ChangePasswordDto {
+  @ApiProperty({ type: String, description: "The caller's current password, re-checked server-side before anything changes." })
+  currentPassword!: string;
+
+  @ApiProperty({ type: String })
+  newPassword!: string;
+}
+
+export class CreateRoleDto {
+  @ApiProperty({ type: String, description: "Stable identifier. Grants and assignments are keyed on it.", example: "billing-manager" })
+  slug!: string;
+
+  @ApiProperty({ type: String, required: false, description: "Human label for the console. Defaults to the slug.", example: "Billing manager" })
+  displayName?: string;
+
+  @ApiProperty({ type: String, required: false, nullable: true })
+  description?: string | null;
+
+  @ApiProperty({ type: Boolean, required: false, description: "Given to every newly signed-up user. Defaults to false." })
+  isDefault?: boolean;
+
+  @ApiProperty({ type: Boolean, required: false, description: "Defaults to true." })
+  isActive?: boolean;
+}
+
+export class UpdateRoleDto {
+  @ApiProperty({ type: String, required: false })
+  name?: string;
+
+  @ApiProperty({ type: String, required: false })
+  displayName?: string;
+
+  @ApiProperty({ type: String, required: false, nullable: true })
+  description?: string | null;
+
+  @ApiProperty({ type: Boolean, required: false, description: "Given to every newly signed-up user." })
+  isDefault?: boolean;
+
+  @ApiProperty({ type: Boolean, required: false, description: "false suspends the role without deleting it — it stops granting immediately." })
+  isActive?: boolean;
+}
+
+export class UpdateUserDto {
+  @ApiProperty({ type: String, required: false, nullable: true, description: "Unique across the deployment." })
+  firstName?: string | null;
+
+  @ApiProperty({ type: String, required: false, nullable: true, description: "Unique across the deployment." })
+  lastName?: string | null;
+
+  @ApiProperty({ type: String, required: false, nullable: true })
+  displayName?: string | null;
+
+  @ApiProperty({ type: String, required: false, nullable: true, description: "Unique across the deployment." })
+  phone?: string | null;
+
+  @ApiProperty({ type: String, required: false, nullable: true, description: "Unique across the deployment." })
+  username?: string | null;
+
+  @ApiProperty({ type: String, required: false, nullable: true })
+  photo?: string | null;
+
+  @ApiProperty({ type: String, required: false, nullable: true, description: "Date of birth, ISO date (yyyy-mm-dd)." })
+  dob?: string | null;
+
+  @ApiProperty({ type: String, required: false, nullable: true })
+  gender?: string | null;
+
+  @ApiProperty({ type: String, required: false, description: "ISO date (yyyy-mm-dd). Not nullable — omit to leave unchanged." })
+  joinedDate?: string;
+}
+
+export class DeleteReasonDto {
+  @ApiProperty({ type: String, required: false, description: "Free-text note, for whoever reviews the deletion later." })
+  reason?: string;
+}
+
+export class AttachPermissionDto {
+  @ApiProperty({ type: String, description: "Permission slug", example: "billing:manage" })
+  permission!: string;
+}
+
+export class AssignRoleDto {
+  @ApiProperty({ type: String, description: "Role slug", example: "billing-manager" })
+  role!: string;
+}
+
+export class CreateUserDto {
+  @ApiProperty({ type: String, example: "alice@example.com" })
+  email!: string;
+
+  @ApiProperty({ type: String, description: "Set directly — there is no invitation email, the account is usable immediately." })
+  password!: string;
+
+  @ApiProperty({ type: String, required: false, description: "Unique across the deployment." })
+  firstName?: string;
+
+  @ApiProperty({ type: String, required: false, description: "Unique across the deployment." })
+  lastName?: string;
+
+  @ApiProperty({ type: String, required: false })
+  displayName?: string;
+
+  @ApiProperty({ type: String, required: false, description: "Unique across the deployment." })
+  phone?: string;
+
+  @ApiProperty({ type: String, required: false, description: "Unique across the deployment." })
+  username?: string;
+
+  @ApiProperty({ type: String, required: false, description: "Date of birth, ISO date (yyyy-mm-dd)." })
+  dob?: string;
+
+  @ApiProperty({ type: String, required: false })
+  gender?: string;
+
+  @ApiProperty({ type: String, required: false, description: "ISO date (yyyy-mm-dd). Defaults to today." })
+  joinedDate?: string;
+
+  @ApiProperty({ type: Boolean, required: false, description: "Defaults to true — false creates the account already deactivated." })
+  isActive?: boolean;
+
+  @ApiProperty({ type: [String], required: false, description: "Role slugs to assign. Defaults to whichever roles are flagged isDefault, same as a self-signup." })
+  roles?: string[];
+}
+
+/** One `Permission` row — the catalog as the admin endpoints return it. */
+export class PermissionSummaryDto {
+  @ApiProperty({ type: String })
+  id!: string;
+
+  @ApiProperty({ type: String, description: "The ability itself: `@CheckAbility(slug)` on the server, `ability.can(slug, ABILITY_SUBJECT)` in a client.", example: "users:read" })
+  slug!: string;
+
+  @ApiProperty({ type: String, example: "List users" })
+  displayName!: string;
+
+  @ApiProperty({ type: String, nullable: true })
+  description!: string | null;
+
+  @ApiProperty({ type: String, description: "Console grouping — a permission matrix renders one section per group.", example: "Users" })
+  group!: string;
+
+  @ApiProperty({ type: Number })
+  groupOrder!: number;
+
+  @ApiProperty({ type: Number })
+  order!: number;
+
+  @ApiProperty({ type: Boolean, description: "false takes the permission out of every ability that would otherwise carry it, without unpicking a single grant." })
+  isActive!: boolean;
+}
+
+export class PermissionListResponseDto {
+  @ApiProperty({ type: [PermissionSummaryDto] })
+  permissions!: PermissionSummaryDto[];
+}
+
+export class DefinePermissionDto {
+  @ApiProperty({ type: String, example: "billing:manage" })
+  slug!: string;
+
+  @ApiProperty({ type: String, required: false, description: "Defaults to the slug when creating." })
+  displayName?: string;
+
+  @ApiProperty({ type: String, required: false, nullable: true })
+  description?: string | null;
+
+  @ApiProperty({ type: String, required: false, description: 'Defaults to "Custom" when creating.' })
+  group?: string;
+
+  @ApiProperty({ type: Number, required: false })
+  groupOrder?: number;
+
+  @ApiProperty({ type: Number, required: false })
+  order?: number;
+
+  @ApiProperty({ type: Boolean, required: false, description: "Set false to switch the capability off deployment-wide, effective on the next request." })
+  isActive?: boolean;
+}
+
+export class GrantPermissionDto {
+  @ApiProperty({ type: String, example: "billing:manage" })
+  permission!: string;
+}
+
+// ---- responses ----
+
+export class AuthTokensDto {
+  @ApiProperty({ type: String })
+  accessToken!: string;
+
+  @ApiProperty({ type: String })
+  refreshToken!: string;
+
+  @ApiProperty({ type: String })
+  sessionId!: string;
+}
+
+export class RefreshResponseDto {
+  @ApiProperty({ type: String })
+  accessToken!: string;
+
+  @ApiProperty({ type: String })
+  refreshToken!: string;
+}
+
+export class TwoFactorChallengeDto {
+  @ApiProperty({ type: Boolean, enum: [true] })
+  twoFactorRequired!: true;
+
+  @ApiProperty({ type: String })
+  challengeToken!: string;
+}
+
+export class CurrentUserDto {
+  @ApiProperty({ type: String, description: "User id" })
+  sub!: string;
+
+  @ApiProperty({ type: String })
+  sessionId!: string;
+
+  @ApiProperty({ type: [String] })
+  roles!: string[];
+
+  @ApiProperty({
+    type: [String],
+    description:
+      "Permission slugs. `defineAbilitiesFor(permissions)` from src/ability.ts rebuilds, in the client, the very ability the server's own guard just answered with — " +
+      "so the console holds no second copy of the rules and cannot offer an action the API will refuse.",
+    example: ["users:read", "audit-log:read"],
+  })
+  permissions!: string[];
+
+  @ApiProperty({ type: Boolean })
+  twoFactorEnabled!: boolean;
+
+  @ApiProperty({ type: String })
+  email!: string;
+
+  @ApiProperty({ type: String, nullable: true })
+  firstName!: string | null;
+
+  @ApiProperty({ type: String, nullable: true })
+  lastName!: string | null;
+
+  @ApiProperty({ type: String, nullable: true })
+  displayName!: string | null;
+
+  @ApiProperty({ type: String, nullable: true })
+  phone!: string | null;
+
+  @ApiProperty({ type: String, nullable: true })
+  username!: string | null;
+
+  @ApiProperty({ type: String, nullable: true, description: "A data URI or an externally-hosted URL — stored as-is, never processed server-side." })
+  photo!: string | null;
+}
+
+/** `PATCH /auth/me`'s response — the same shape whether or not the combo has workspaces, since a profile isn't a workspace concept. */
+export class SelfProfileDto {
+  @ApiProperty({ type: String })
+  id!: string;
+
+  @ApiProperty({ type: String })
+  email!: string;
+
+  @ApiProperty({ type: String, nullable: true })
+  firstName!: string | null;
+
+  @ApiProperty({ type: String, nullable: true })
+  lastName!: string | null;
+
+  @ApiProperty({ type: String, nullable: true })
+  displayName!: string | null;
+
+  @ApiProperty({ type: String, nullable: true })
+  phone!: string | null;
+
+  @ApiProperty({ type: String, nullable: true })
+  username!: string | null;
+
+  @ApiProperty({ type: String, nullable: true, description: "A data URI or an externally-hosted URL — stored as-is, never processed server-side." })
+  photo!: string | null;
+
+  @ApiProperty({ type: String, format: "date-time" })
+  createdAt!: string;
+}
+
+/** One live session, as a "your devices" screen would render it. Revoked and expired rows are not returned. */
+export class SessionSummaryDto {
+  @ApiProperty({ type: String })
+  id!: string;
+
+  @ApiProperty({ type: String })
+  createdAt!: string;
+
+  @ApiProperty({ type: String, description: "Absolute cut-off, fixed when the session was created. Refreshing does not extend it." })
+  expiresAt!: string;
+
+  @ApiProperty({ type: String, required: false, description: "The OAuth provider this login came through; absent for a password login.", example: "google" })
+  provider?: string;
+
+  @ApiProperty({ type: String, required: false })
+  userAgent?: string;
+
+  @ApiProperty({ type: String, required: false })
+  ip?: string;
+}
+
+export class OkResponseDto {
+  @ApiProperty({ type: Boolean, enum: [true] })
+  ok!: true;
+}
+
+export class EnrollTwoFactorResponseDto {
+  @ApiProperty({ type: String, description: "Base32 TOTP secret" })
+  secret!: string;
+
+  @ApiProperty({ type: String, description: "otpauth:// provisioning URI, render as a QR code" })
+  provisioningUri!: string;
+}
+
+export class ConfirmTwoFactorResponseDto {
+  @ApiProperty({ type: [String], description: "One-time recovery codes — shown once" })
+  backupCodes!: string[];
+}
+
+export class OAuthStartResponseDto {
+  @ApiProperty({ type: String, description: "Redirect the user/webview to this URL to start the OAuth flow" })
+  url!: string;
+}
+
+export class RoleSummaryDto {
+  @ApiProperty({ type: String })
+  id!: string;
+
+  @ApiProperty({ type: String })
+  slug!: string;
+
+  @ApiProperty({ type: String })
+  displayName!: string;
+
+  @ApiProperty({ type: Boolean, description: "Given to every new user (or, in the workspace variant, every new membership)." })
+  isDefault!: boolean;
+
+  @ApiProperty({ type: Boolean })
+  isActive!: boolean;
+}
+
+export class RoleListResponseDto {
+  @ApiProperty({ type: [RoleSummaryDto] })
+  roles!: RoleSummaryDto[];
+}

package/registry/combos/nestjs-drizzle/shared/src/id.helper.ts

@@ -0,0 +1,22 @@
+// Primary keys are BigInt for join/index performance; registry/core's types (SessionRecord,
+// Revoker, etc.) deliberately stay opaque `string` identifiers so core has zero DB awareness.
+// This is the one conversion point between the two, at each repository's Drizzle boundary —
+// never call BigInt(...)/.toString() ad hoc, since a malformed value should 400, not throw an
+// uncaught SyntaxError.
+export function toId(value: string | number | bigint): bigint {
+  try {
+    return BigInt(value);
+  } catch {
+    throw new Error(`Invalid id: ${value}`);
+  }
+}
+
+export function toIdOrUndefined(value: string | number | bigint | null | undefined): bigint | undefined {
+  if (value === null || value === undefined || value === "") return undefined;
+  return toId(value);
+}
+
+export function toIdOrNull(value: string | number | bigint | null | undefined): bigint | null {
+  if (value === null || value === undefined || value === "") return null;
+  return toId(value);
+}

package/registry/combos/nestjs-drizzle/shared/src/key-provider.ts

@@ -0,0 +1,51 @@
+// NOTE: the `@/lib/auth/core/*` import path below is a placeholder the CLI rewrites
+// to your project's actual path alias at install time (see registry.json).
+import { createHash } from "node:crypto";
+import { Injectable } from "@nestjs/common";
+import type { JwtSigningKey } from "@/lib/auth/core/types.js";
+
+const ENV_VAR = "AUTH_JWT_SECRET";
+const MIN_SECRET_BYTES = 32; // 256 bits, HS256's own minimum
+
+function loadSecret(): Uint8Array {
+  const raw = process.env[ENV_VAR];
+  if (!raw) {
+    throw new Error(`${ENV_VAR} is not set. Generate one and set it before starting the app — e.g.: openssl rand -base64 32`);
+  }
+  const secret = Buffer.from(raw, "base64");
+  if (secret.length < MIN_SECRET_BYTES) {
+    throw new Error(`${ENV_VAR} decodes to ${secret.length} bytes — needs at least ${MIN_SECRET_BYTES} (256 bits) for HS256.`);
+  }
+  return secret;
+}
+
+/**
+ * One static HS256 secret, read once from `AUTH_JWT_SECRET` at process start. No database, no
+ * generation, no rotation: the secret is deployment configuration, the same way `DATABASE_URL`
+ * is — losing it (or changing it) invalidates every outstanding token, which is the same
+ * failure mode an RSA keypair rotation has for its *retired* keys, just without the grace
+ * window this library previously bought by keeping old keys verifiable in the database.
+ *
+ * `kid` is derived from the secret (a hash prefix) rather than configured separately, so it
+ * changes automatically whenever the secret does, with nothing else to keep in sync. It is
+ * carried in the JWT header for tooling/debugging only — `token-service.ts`'s verify path does
+ * not consult it, because there is only ever one secret in play.
+ */
+@Injectable()
+export class KeyProviderService {
+  private readonly key: JwtSigningKey;
+
+  constructor() {
+    const secret = loadSecret();
+    const kid = createHash("sha256").update(secret).digest("hex").slice(0, 12);
+    this.key = { kid, secret };
+  }
+
+  async getActiveKey(): Promise<JwtSigningKey> {
+    return this.key;
+  }
+
+  get secret(): Uint8Array {
+    return this.key.secret;
+  }
+}

package/registry/combos/nestjs-drizzle/shared/src/oauth.repository.ts

@@ -0,0 +1,36 @@
+import { BadRequestException, Inject, Injectable } from "@nestjs/common";
+import { and, eq } from "drizzle-orm";
+import type { OAuthStoreDeps } from "@/lib/auth/core/oauth.js";
+import { DRIZZLE_DB, type Database } from "./db.js";
+import { oauthAccounts, users } from "./schema.js";
+import { toId } from "./id.helper.js";
+
+@Injectable()
+export class OAuthRepository implements OAuthStoreDeps {
+  constructor(@Inject(DRIZZLE_DB) private readonly db: Database) {}
+
+  async findAccountByProvider(provider: string, providerAccountId: string): Promise<{ userId: string } | null> {
+    const [row] = await this.db
+      .select()
+      .from(oauthAccounts)
+      .where(and(eq(oauthAccounts.provider, provider), eq(oauthAccounts.providerAccountId, providerAccountId)))
+      .limit(1);
+    return row ? { userId: row.userId.toString() } : null;
+  }
+
+  async linkAccount(input: { userId: string; provider: string; providerAccountId: string; email?: string }): Promise<void> {
+    await this.db.insert(oauthAccounts).values({ ...input, userId: toId(input.userId) });
+  }
+
+  async findUserByVerifiedEmail(email: string): Promise<{ id: string } | null> {
+    const [row] = await this.db.select().from(users).where(eq(users.email, email)).limit(1);
+    return row ? { id: row.id.toString() } : null;
+  }
+
+  /** OAuth-only signup: no password is ever set, which is why `User.passwordHash` is nullable. */
+  async createUserFromOAuth(input: { email?: string }): Promise<{ id: string }> {
+    if (!input.email) throw new BadRequestException("OAuth provider did not return an email address");
+    const [row] = await this.db.insert(users).values({ email: input.email, passwordHash: null }).returning();
+    return { id: row.id.toString() };
+  }
+}

package/registry/combos/nestjs-drizzle/shared/src/pagination.ts

@@ -0,0 +1,30 @@
+export interface PageMeta {
+  page: number;
+  limit: number;
+  total: number;
+  pageCount: number;
+  hasPreviousPage: boolean;
+  hasNextPage: boolean;
+}
+
+export interface Paginated<T> {
+  items: T[];
+  meta: PageMeta;
+}
+
+export const DEFAULT_PAGE_SIZE = 25;
+export const MAX_PAGE_SIZE = 100;
+
+/** `page` is 1-indexed, matching every list endpoint's `?page=` query param. */
+export function normalizePage(page: number | undefined): number {
+  return page && page > 0 ? Math.floor(page) : 1;
+}
+
+export function normalizeLimit(limit: number | undefined): number {
+  return Math.min(limit && limit > 0 ? Math.floor(limit) : DEFAULT_PAGE_SIZE, MAX_PAGE_SIZE);
+}
+
+export function buildPageMeta(page: number, limit: number, total: number): PageMeta {
+  const pageCount = Math.ceil(total / limit);
+  return { page, limit, total, pageCount, hasPreviousPage: page > 1, hasNextPage: page < pageCount };
+}

package/registry/combos/nestjs-drizzle/shared/src/password-reset.repository.ts

@@ -0,0 +1,29 @@
+import { Inject, Injectable } from "@nestjs/common";
+import { eq } from "drizzle-orm";
+import type { PasswordResetStoreDeps } from "@/lib/auth/core/password-reset.js";
+import { DRIZZLE_DB, type Database } from "./db.js";
+import { passwordResetTokens, users } from "./schema.js";
+import { toId } from "./id.helper.js";
+
+@Injectable()
+export class PasswordResetRepository implements PasswordResetStoreDeps {
+  constructor(@Inject(DRIZZLE_DB) private readonly db: Database) {}
+
+  async saveResetToken(input: { userId: string; tokenHash: string; expiresAt: string }): Promise<void> {
+    await this.db.insert(passwordResetTokens).values({ userId: toId(input.userId), tokenHash: input.tokenHash, expiresAt: new Date(input.expiresAt) });
+  }
+
+  async findValidResetToken(tokenHash: string): Promise<{ userId: string; expiresAt: string; consumedAt: string | null } | null> {
+    const [row] = await this.db.select().from(passwordResetTokens).where(eq(passwordResetTokens.tokenHash, tokenHash)).limit(1);
+    if (!row) return null;
+    return { userId: row.userId.toString(), expiresAt: row.expiresAt.toISOString(), consumedAt: row.consumedAt?.toISOString() ?? null };
+  }
+
+  async consumeResetToken(tokenHash: string): Promise<void> {
+    await this.db.update(passwordResetTokens).set({ consumedAt: new Date() }).where(eq(passwordResetTokens.tokenHash, tokenHash));
+  }
+
+  async setPasswordHash(userId: string, passwordHash: string): Promise<void> {
+    await this.db.update(users).set({ passwordHash }).where(eq(users.id, toId(userId)));
+  }
+}