@podosoft/podokit 0.17.3 → 1.0.1

package/dist/templates/modules/auth/files/apps/api/src/auth-config/auth-config.service.ts

@@ -1,7 +1,5 @@
-import { BadRequestException, Injectable } from "@nestjs/common";
-import { InjectRepository } from "@nestjs/typeorm";
-import { Repository } from "typeorm";
-import { AuthConfigRow } from "./auth-config.entity";
+import type { SQL } from "bun";
+import { AppException } from "@podosoft/podokit-contracts";
 import {
   DEFAULT_SESSION_LIFETIME_SECONDS,
   encryptSecret,
@@ -14,18 +12,26 @@ import {
 } from "@podosoft/podokit-auth";
 import { refreshAuthNow } from "../auth/auth-provider";
 
-/** One configured social provider as shown to the admin (no secret — just a
- *  `hasSecret` flag). */
-export type SocialProviderView = { id: string; enabled: boolean; clientId: string; redirectURI: string; hasSecret: boolean };
+export type SocialProviderView = {
+  id: string;
+  enabled: boolean;
+  clientId: string;
+  redirectURI: string;
+  hasSecret: boolean;
+};
 
-/** Admin-facing view — non-secret fields plus a `hasSecret` flag. Never exposes
- *  the stored client secret / SMTP password. Social providers are dynamic: the
- *  map holds one entry per configured provider (google, github, apple, …). */
 export type AuthConfigView = {
   social: Record<string, SocialProviderView>;
-  /** Catalog of addable providers (id + display label) for the "add provider" picker. */
   catalog: ReadonlyArray<{ id: string; label: string }>;
-  smtp: { enabled: boolean; host: string; port: number; secure: boolean; user: string; from: string; hasSecret: boolean };
+  smtp: {
+    enabled: boolean;
+    host: string;
+    port: number;
+    secure: boolean;
+    user: string;
+    from: string;
+    hasSecret: boolean;
+  };
   server: {
     requireEmailVerification: boolean;
     requireSignupApproval: boolean;
@@ -36,11 +42,25 @@ export type AuthConfigView = {
   };
 };
 
-type ProviderUpdate = { enabled?: boolean; clientId?: string; clientSecret?: string; redirectURI?: string; delete?: boolean };
+export type ProviderUpdate = {
+  enabled?: boolean;
+  clientId?: string;
+  clientSecret?: string;
+  redirectURI?: string;
+  delete?: boolean;
+};
+
 export type AuthConfigUpdate = {
-  /** Per-provider upsert (keyed by provider id); `{ delete: true }` removes it. */
   social?: Record<string, ProviderUpdate>;
-  smtp?: { enabled?: boolean; host?: string; port?: number; secure?: boolean; user?: string; pass?: string; from?: string };
+  smtp?: {
+    enabled?: boolean;
+    host?: string;
+    port?: number;
+    secure?: boolean;
+    user?: string;
+    pass?: string;
+    from?: string;
+  };
   server?: {
     requireEmailVerification?: boolean;
     requireSignupApproval?: boolean;
@@ -51,129 +71,223 @@ export type AuthConfigUpdate = {
   };
 };
 
-@Injectable()
+interface AuthConfigRow {
+  key: string;
+  enabled: boolean;
+  config: unknown;
+  secret: string | null;
+}
+
+function object(value: unknown): Record<string, unknown> {
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>;
+  }
+  if (typeof value === "string") {
+    try {
+      return object(JSON.parse(value) as unknown);
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+function stringField(source: Record<string, unknown>, key: string): string {
+  const value = source[key];
+  return typeof value === "string" ? value : "";
+}
+
+function booleanField(source: Record<string, unknown>, key: string, fallback: boolean): boolean {
+  return typeof source[key] === "boolean" ? source[key] : fallback;
+}
+
 export class AuthConfigService {
-  constructor(@InjectRepository(AuthConfigRow) private readonly repo: Repository<AuthConfigRow>) {}
+  constructor(private readonly sql: SQL) {}
 
-  async describe(): Promise<AuthConfigView> {
-    const rows = await this.repo.find();
-    const byKey = new Map(rows.map((r) => [r.key, r]));
-    const env = envAuthConfig();
+  private async rows(): Promise<AuthConfigRow[]> {
+    return this.sql<AuthConfigRow[]>`
+      SELECT "key", "enabled", "config", "secret" FROM "auth_config"
+    `;
+  }
+
+  private async row(key: string): Promise<AuthConfigRow | null> {
+    const rows = await this.sql<AuthConfigRow[]>`
+      SELECT "key", "enabled", "config", "secret"
+      FROM "auth_config" WHERE "key" = ${key}
+    `;
+    return rows[0] ?? null;
+  }
+
+  private async upsert(row: AuthConfigRow): Promise<void> {
+    const config = object(row.config);
+    await this.sql`
+      INSERT INTO "auth_config" ("key", "enabled", "config", "secret", "updatedAt")
+      VALUES (${row.key}, ${row.enabled}, ${config}, ${row.secret}, CURRENT_TIMESTAMP)
+      ON CONFLICT ("key") DO UPDATE SET
+        "enabled" = EXCLUDED."enabled",
+        "config" = EXCLUDED."config",
+        "secret" = EXCLUDED."secret",
+        "updatedAt" = CURRENT_TIMESTAMP
+    `;
+  }
 
+  async describe(): Promise<AuthConfigView> {
+    const rows = await this.rows();
+    const byKey = new Map(rows.map((row) => [row.key, row]));
+    const environment = envAuthConfig();
     const social: Record<string, SocialProviderView> = {};
+
     for (const row of rows) {
       if (!row.key.startsWith("social.")) continue;
       const id = row.key.slice("social.".length);
       if (!SUPPORTED_PROVIDER_IDS.has(id)) continue;
-      const c = (row.config ?? {}) as { clientId?: string; redirectURI?: string };
-      social[id] = { id, enabled: row.enabled, clientId: c.clientId ?? "", redirectURI: c.redirectURI ?? "", hasSecret: !!row.secret };
+      const config = object(row.config);
+      social[id] = {
+        id,
+        enabled: row.enabled,
+        clientId: stringField(config, "clientId"),
+        redirectURI: stringField(config, "redirectURI"),
+        hasSecret: row.secret !== null && row.secret.length > 0,
+      };
     }
-    // Surface env-configured providers (google/github) that have no DB row yet, so
-    // the admin sees them as already-active rather than missing.
-    for (const [id, p] of Object.entries(env.social)) {
-      if (!social[id]) social[id] = { id, enabled: p.enabled, clientId: p.clientId, redirectURI: p.redirectURI ?? "", hasSecret: !!p.clientSecret };
+    for (const [id, provider] of Object.entries(environment.social)) {
+      if (social[id]) continue;
+      social[id] = {
+        id,
+        enabled: provider.enabled,
+        clientId: provider.clientId,
+        redirectURI: provider.redirectURI ?? "",
+        hasSecret: provider.clientSecret.length > 0,
+      };
     }
 
-    const smtpRow = byKey.get("smtp");
-    const smtpC = (smtpRow?.config ?? {}) as { host?: string; port?: number; secure?: boolean; user?: string; from?: string };
-    const serverRow = byKey.get("server");
-    const serverC = (serverRow?.config ?? {}) as {
-      requireEmailVerification?: boolean;
-      requireSignupApproval?: boolean;
-      allowDelete?: boolean;
-      hibp?: boolean;
-      auditLog?: boolean;
-      sessionIdleTimeoutMinutes?: number | null;
-    };
+    const smtp = byKey.get("smtp");
+    const smtpConfig = object(smtp?.config);
+    const serverConfig = object(byKey.get("server")?.config);
     return {
       social,
       catalog: SUPPORTED_SOCIAL_PROVIDERS,
       smtp: {
-        enabled: smtpRow?.enabled ?? false,
-        host: smtpC.host ?? "",
-        port: smtpC.port ?? 587,
-        secure: smtpC.secure ?? false,
-        user: smtpC.user ?? "",
-        from: smtpC.from ?? "",
-        hasSecret: !!smtpRow?.secret,
+        enabled: smtp?.enabled ?? false,
+        host: stringField(smtpConfig, "host"),
+        port: typeof smtpConfig.port === "number" ? smtpConfig.port : 587,
+        secure: booleanField(smtpConfig, "secure", false),
+        user: stringField(smtpConfig, "user"),
+        from: stringField(smtpConfig, "from"),
+        hasSecret: smtp?.secret !== null && smtp?.secret !== undefined && smtp.secret.length > 0,
       },
       server: {
-        requireEmailVerification: serverC.requireEmailVerification ?? env.requireEmailVerification,
-        requireSignupApproval: serverC.requireSignupApproval ?? env.requireSignupApproval,
-        allowDelete: serverC.allowDelete ?? env.allowDelete,
-        hibp: serverC.hibp ?? env.hibp,
-        auditLog: serverC.auditLog ?? env.auditLog,
+        requireEmailVerification: booleanField(
+          serverConfig,
+          "requireEmailVerification",
+          environment.requireEmailVerification,
+        ),
+        requireSignupApproval: booleanField(
+          serverConfig,
+          "requireSignupApproval",
+          environment.requireSignupApproval,
+        ),
+        allowDelete: booleanField(serverConfig, "allowDelete", environment.allowDelete),
+        hibp: booleanField(serverConfig, "hibp", environment.hibp),
+        auditLog: booleanField(serverConfig, "auditLog", environment.auditLog),
         sessionIdleTimeoutMinutes: resolveSessionIdleTimeoutMinutes(
-          serverC.sessionIdleTimeoutMinutes,
-          env.sessionIdleTimeoutMinutes,
+          serverConfig.sessionIdleTimeoutMinutes,
+          environment.sessionIdleTimeoutMinutes,
         ),
       },
     };
   }
 
-  async update(dto: AuthConfigUpdate): Promise<AuthConfigView> {
-    for (const [id, u] of Object.entries(dto.social ?? {})) {
-      if (!SUPPORTED_PROVIDER_IDS.has(id)) throw new BadRequestException(`Unsupported social provider: ${id}`);
-      if (u.delete) await this.repo.delete({ key: socialKey(id) });
-      else await this.upsertProvider(socialKey(id), u);
+  async update(update: AuthConfigUpdate): Promise<AuthConfigView> {
+    for (const [id, provider] of Object.entries(update.social ?? {})) {
+      if (!SUPPORTED_PROVIDER_IDS.has(id)) {
+        throw new AppException("AUTH_PROVIDER_UNSUPPORTED", `Unsupported social provider: ${id}`, 400);
+      }
+      const key = socialKey(id);
+      if (provider.delete) await this.sql`DELETE FROM "auth_config" WHERE "key" = ${key}`;
+      else await this.upsertProvider(key, provider);
     }
-    if (dto.smtp) await this.upsertSmtp(dto.smtp);
-    if (dto.server) await this.upsertServer(dto.server);
+    if (update.smtp) await this.upsertSmtp(update.smtp);
+    if (update.server) await this.upsertServer(update.server);
     await refreshAuthNow();
-    if (dto.server?.sessionIdleTimeoutMinutes !== undefined) {
-      await this.resetSessionExpirations(dto.server.sessionIdleTimeoutMinutes);
+    if (update.server?.sessionIdleTimeoutMinutes !== undefined) {
+      await this.resetSessionExpirations(update.server.sessionIdleTimeoutMinutes);
     }
     return this.describe();
   }
 
-  private async upsertProvider(key: string, u: ProviderUpdate): Promise<void> {
-    const row = (await this.repo.findOneBy({ key })) ?? this.repo.create({ key, enabled: false, config: {}, secret: null });
-    const config = { ...(row.config as { clientId?: string; redirectURI?: string }) };
-    if (u.clientId !== undefined) config.clientId = u.clientId;
-    if (u.redirectURI !== undefined) config.redirectURI = u.redirectURI;
-    if (u.enabled !== undefined) row.enabled = u.enabled;
-    // Replace the secret only when a non-empty value is supplied; otherwise keep it.
-    if (u.clientSecret) row.secret = encryptSecret(u.clientSecret);
-    row.config = config;
-    await this.repo.save(row);
+  private async upsertProvider(key: string, update: ProviderUpdate): Promise<void> {
+    const current = await this.row(key) ?? { key, enabled: false, config: {}, secret: null };
+    const config = object(current.config);
+    if (update.clientId !== undefined) config.clientId = update.clientId;
+    if (update.redirectURI !== undefined) config.redirectURI = update.redirectURI;
+    await this.upsert({
+      ...current,
+      enabled: update.enabled ?? current.enabled,
+      config,
+      secret: update.clientSecret ? encryptSecret(update.clientSecret) : current.secret,
+    });
   }
 
-  private async upsertSmtp(u: NonNullable<AuthConfigUpdate["smtp"]>): Promise<void> {
-    const row = (await this.repo.findOneBy({ key: "smtp" })) ?? this.repo.create({ key: "smtp", enabled: false, config: {}, secret: null });
-    const config = { ...(row.config as Record<string, unknown>) };
-    for (const f of ["host", "port", "secure", "user", "from"] as const) if (u[f] !== undefined) config[f] = u[f];
-    if (u.enabled !== undefined) row.enabled = u.enabled;
-    if (u.pass) row.secret = encryptSecret(u.pass);
-    row.config = config;
-    await this.repo.save(row);
+  private async upsertSmtp(update: NonNullable<AuthConfigUpdate["smtp"]>): Promise<void> {
+    const current = await this.row("smtp") ?? {
+      key: "smtp",
+      enabled: false,
+      config: {},
+      secret: null,
+    };
+    const config = object(current.config);
+    for (const field of ["host", "port", "secure", "user", "from"] as const) {
+      if (update[field] !== undefined) config[field] = update[field];
+    }
+    await this.upsert({
+      ...current,
+      enabled: update.enabled ?? current.enabled,
+      config,
+      secret: update.pass ? encryptSecret(update.pass) : current.secret,
+    });
   }
 
-  private async upsertServer(u: NonNullable<AuthConfigUpdate["server"]>): Promise<void> {
-    if (u.sessionIdleTimeoutMinutes !== undefined && !isSessionIdleTimeoutMinutes(u.sessionIdleTimeoutMinutes)) {
-      throw new BadRequestException("Session idle timeout must be null or an integer from 5 to 10080 minutes");
+  private async upsertServer(update: NonNullable<AuthConfigUpdate["server"]>): Promise<void> {
+    if (
+      update.sessionIdleTimeoutMinutes !== undefined
+      && !isSessionIdleTimeoutMinutes(update.sessionIdleTimeoutMinutes)
+    ) {
+      throw new AppException(
+        "SESSION_IDLE_TIMEOUT_INVALID",
+        "Session idle timeout must be null or an integer from 5 to 10080 minutes",
+        400,
+      );
     }
-    const row = (await this.repo.findOneBy({ key: "server" })) ?? this.repo.create({ key: "server", enabled: true, config: {}, secret: null });
-    const config = { ...(row.config as Record<string, unknown>) };
-    for (const f of ["requireEmailVerification", "requireSignupApproval", "allowDelete", "hibp", "auditLog"] as const) {
-      if (u[f] !== undefined) config[f] = u[f];
+    const current = await this.row("server") ?? {
+      key: "server",
+      enabled: true,
+      config: {},
+      secret: null,
+    };
+    const config = object(current.config);
+    for (const field of [
+      "requireEmailVerification",
+      "requireSignupApproval",
+      "allowDelete",
+      "hibp",
+      "auditLog",
+    ] as const) {
+      if (update[field] !== undefined) config[field] = update[field];
     }
-    if (u.sessionIdleTimeoutMinutes !== undefined) {
-      config.sessionIdleTimeoutMinutes = u.sessionIdleTimeoutMinutes;
+    if (update.sessionIdleTimeoutMinutes !== undefined) {
+      config.sessionIdleTimeoutMinutes = update.sessionIdleTimeoutMinutes;
     }
-    row.config = config;
-    await this.repo.save(row);
+    await this.upsert({ ...current, config });
   }
 
   private async resetSessionExpirations(minutes: number | null): Promise<void> {
-    const lifetimeSeconds = minutes === null
-      ? DEFAULT_SESSION_LIFETIME_SECONDS
-      : minutes * 60;
-    await this.repo.manager.query(
-      `UPDATE "session"
-       SET "expiresAt" = CURRENT_TIMESTAMP + ($1 * INTERVAL '1 second'),
-           "updatedAt" = CURRENT_TIMESTAMP
-       WHERE "expiresAt" > CURRENT_TIMESTAMP`,
-      [lifetimeSeconds],
-    );
+    const lifetimeSeconds = minutes === null ? DEFAULT_SESSION_LIFETIME_SECONDS : minutes * 60;
+    await this.sql`
+      UPDATE "session"
+      SET "expiresAt" = CURRENT_TIMESTAMP + (${lifetimeSeconds} * INTERVAL '1 second'),
+          "updatedAt" = CURRENT_TIMESTAMP
+      WHERE "expiresAt" > CURRENT_TIMESTAMP
+    `;
   }
 }

package/dist/templates/modules/auth/files/apps/api/src/migrations/1720400000000-InitAppSettings.ts

@@ -27,7 +27,8 @@ export class InitAppSettings1720400000000 implements MigrationInterface {
         ('apiKey', 'true'),
         ('passkey', 'true'),
         ('organization', 'true'),
-        ('oidcProvider', 'false')
+        ('oidcProvider', 'false'),
+        ('require2fa', 'false')
       ON CONFLICT ("key") DO NOTHING
     `);
   }

package/dist/templates/modules/auth/files/apps/api/src/settings/app-settings.migration.spec.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "bun:test";
+import type { QueryRunner } from "typeorm";
+import { InitAppSettings1720400000000 } from "../migrations/1720400000000-InitAppSettings";
+
+describe("app setting migration", () => {
+  it("seeds every authentication feature and policy default", async () => {
+    const queries: string[] = [];
+    const runner = {
+      query: (sql: string): Promise<unknown[]> => {
+        queries.push(sql);
+        return Promise.resolve([]);
+      },
+    } as unknown as QueryRunner;
+
+    await new InitAppSettings1720400000000().up(runner);
+
+    const seed = queries.join("\n");
+    for (const key of [
+      "twoFactor",
+      "magicLink",
+      "emailOtp",
+      "username",
+      "multiSession",
+      "phoneNumber",
+      "apiKey",
+      "passkey",
+      "organization",
+      "oidcProvider",
+      "require2fa",
+    ]) {
+      expect(seed).toContain(`('${key}',`);
+    }
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/settings/flag-defaults.ts

@@ -1,7 +1,7 @@
 /** Admin-managed auth feature flags and their shipped defaults.
  *
- *  Kept free of Nest/TypeORM imports so both the DI-managed SettingsService and
- *  the better-auth feature gate (loaded by auth.ts, outside DI — including when
+ *  Kept free of framework/ORM imports so both SettingsService and the Better
+ *  Auth feature gate (loaded by auth.ts, including when
  *  the better-auth CLI evaluates auth.ts for migrations) can import it safely.
  *
  *  Must match the rows seeded by the InitAppSettings migration. phoneNumber is
@@ -21,7 +21,7 @@ export const FLAG_DEFAULTS: Record<FeatureFlag, boolean> = {
   // Acting as an OIDC identity provider is an enterprise opt-in; off by default.
   oidcProvider: false,
   // Policy (not a feature endpoint): when on, every signed-in user must enrol in
-  // two-factor before using the app. Enforced by TwoFactorRequiredGuard + the web
+  // two-factor before using the app. Enforced by AuthService + the web
   // enrolment gate — the feature gate ignores it (no endpoint prefix). Off by default.
   require2fa: false,
 };

package/dist/templates/modules/auth/files/apps/api/src/settings/settings.service.ts

@@ -1,55 +1,51 @@
-import { Injectable, type OnModuleInit } from "@nestjs/common";
-import { InjectRepository } from "@nestjs/typeorm";
-import { Repository } from "typeorm";
-import { AppSetting } from "./app-setting.entity";
-
+import type { SQL } from "bun";
 import { FLAG_DEFAULTS, FEATURE_FLAGS, type FeatureFlag } from "./flag-defaults";
 
-/** Admin-editable feature flags — the DB (app_setting) is the single source of
- *  truth. Defaults are seeded by the InitAppSettings migration and changed live
- *  from the admin Settings page. Only features whose plugin can be mounted
- *  unconditionally live here; their endpoints are blocked server-side when off
- *  (see auth/feature-gate.ts). Server-enforced flags (email verification, breach
- *  check, self-deletion) and secrets/infra stay in the environment. */
 export { FEATURE_FLAGS, type FeatureFlag };
 
-@Injectable()
-export class SettingsService implements OnModuleInit {
-  private cache = new Map<string, string>();
+interface AppSettingRow {
+  key: string;
+  value: string;
+}
 
-  constructor(@InjectRepository(AppSetting) private readonly repo: Repository<AppSetting>) {}
+/** DB-backed feature flags with migration defaults as the source of truth. */
+export class SettingsService {
+  private cache = new Map<string, string>();
 
-  async onModuleInit(): Promise<void> {
-    await this.refresh();
-  }
+  constructor(private readonly sql: SQL) {}
 
-  private async refresh(): Promise<void> {
+  async refresh(): Promise<void> {
     try {
-      const rows = await this.repo.find();
-      this.cache = new Map(rows.map((r) => [r.key, r.value]));
+      const rows = await this.sql<AppSettingRow[]>`
+        SELECT "key", "value" FROM "app_setting"
+      `;
+      this.cache = new Map(rows.map((row) => [row.key, row.value]));
     } catch {
-      // Table not migrated yet — fall back to the shipped defaults until it exists.
       this.cache = new Map();
     }
   }
 
-  /** DB value (migration-seeded or admin-set); shipped default if the row is missing. */
   getBool(flag: FeatureFlag): boolean {
     const stored = this.cache.get(flag);
-    if (stored !== undefined) return stored === "true";
-    return FLAG_DEFAULTS[flag];
+    return stored === undefined ? FLAG_DEFAULTS[flag] : stored === "true";
   }
 
   flags(): Record<FeatureFlag, boolean> {
-    return Object.fromEntries(FEATURE_FLAGS.map((f) => [f, this.getBool(f)])) as Record<FeatureFlag, boolean>;
+    return Object.fromEntries(
+      FEATURE_FLAGS.map((flag) => [flag, this.getBool(flag)]),
+    ) as Record<FeatureFlag, boolean>;
   }
 
   async setMany(update: Partial<Record<FeatureFlag, boolean>>): Promise<Record<FeatureFlag, boolean>> {
     for (const flag of FEATURE_FLAGS) {
-      const next = update[flag];
-      if (typeof next === "boolean") {
-        await this.repo.save({ key: flag, value: String(next) });
-      }
+      const value = update[flag];
+      if (typeof value !== "boolean") continue;
+      await this.sql`
+        INSERT INTO "app_setting" ("key", "value", "updatedAt")
+        VALUES (${flag}, ${String(value)}, CURRENT_TIMESTAMP)
+        ON CONFLICT ("key") DO UPDATE
+        SET "value" = EXCLUDED."value", "updatedAt" = CURRENT_TIMESTAMP
+      `;
     }
     await this.refresh();
     return this.flags();

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/SKILL.md

@@ -22,7 +22,7 @@ Use the generated `auth:configure` command so credentials enter the encrypted `a
 3. Run Better Auth and TypeORM migrations before configuring a new app:
 
    ```bash
-   npm run migrate:all -w <app>-api
+   {{apiRun}} migrate:all
    ```
 
 4. Create or verify the initial administrator with `admin:bootstrap` before enabling mandatory email verification or other runtime authentication settings.
@@ -53,8 +53,8 @@ credentials for `auth:configure`:
 
 ```bash
 export ADMIN_EMAILS="admin@example.com"
-npm run admin:bootstrap -w <app>-api -- --dry-run
-npm run admin:bootstrap -w <app>-api
+{{apiRun}} admin:bootstrap -- --dry-run
+{{apiRun}} admin:bootstrap
 ```
 
 Unset sensitive variables when finished:
@@ -68,13 +68,13 @@ unset AUTH_SETUP_ADMIN_PASSWORD OAUTH_CLIENT_SECRET SMTP_PASS
 Preview a redacted plan first:
 
 ```bash
-npm run auth:configure -w <app>-api -- --provider google --require-signup-approval --dry-run
+{{apiRun}} auth:configure -- --provider google --require-signup-approval --dry-run
 ```
 
 Apply OAuth credentials and the approval policy:
 
 ```bash
-npm run auth:configure -w <app>-api -- --provider google --require-signup-approval
+{{apiRun}} auth:configure -- --provider google --require-signup-approval
 ```
 
 Configure SMTP separately or in the same run. Passwordless IP-based relays may omit `SMTP_USER` and `SMTP_PASS`.
@@ -84,7 +84,7 @@ export SMTP_HOST="smtp-relay.example.com"
 export SMTP_PORT="587"
 export SMTP_SECURE="false"
 export MAIL_FROM="Example <noreply@example.com>"
-npm run auth:configure -w <app>-api -- --smtp
+{{apiRun}} auth:configure -- --smtp
 ```
 
 ## Verify
@@ -92,7 +92,7 @@ npm run auth:configure -w <app>-api -- --smtp
 1. Check the public capability snapshot:
 
    ```bash
-   npm run auth:configure -w <app>-api -- --provider google --check-only
+   {{apiRun}} auth:configure -- --provider google --check-only
    ```
 
 2. Open `/login` and confirm the provider button appears.

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/references/bootstrap-admin.md

@@ -30,9 +30,9 @@ fallbacks so the same ephemeral values can immediately configure OAuth and SMTP.
 ## Preview, create, and verify
 
 ```bash
-npm run admin:bootstrap -w <app>-api -- --dry-run
-npm run admin:bootstrap -w <app>-api
-npm run admin:bootstrap -w <app>-api -- --check-only
+{{apiRun}} admin:bootstrap -- --dry-run
+{{apiRun}} admin:bootstrap
+{{apiRun}} admin:bootstrap -- --check-only
 ```
 
 The create path writes `role=admin`, `emailVerified=true`, and

package/dist/templates/modules/auth/files/dot-claude/skills/podokit-configure-auth/references/google.md

@@ -34,8 +34,8 @@ preview deployment. Use a separate Google Cloud project and Web client for devel
    export AUTH_SETUP_ADMIN_PASSWORD="<from-secret-manager>"
    export OAUTH_CLIENT_ID="<google-client-id>"
    export OAUTH_CLIENT_SECRET="<from-secret-manager>"
-   npm run auth:configure -w <app>-api -- --provider google --dry-run
-   npm run auth:configure -w <app>-api -- --provider google
+   {{apiRun}} auth:configure -- --provider google --dry-run
+   {{apiRun}} auth:configure -- --provider google
    ```
 
    If only an existing callback is stale, keep the stored client ID, client
@@ -43,7 +43,7 @@ preview deployment. Use a separate Google Cloud project and Web client for devel
 
    ```bash
    AUTH_SETUP_ORIGIN=https://app-dev.example.com \
-     npm run auth:configure -w <app>-api -- --provider google --redirect-only
+     {{apiRun}} auth:configure -- --provider google --redirect-only
    ```
 
 5. Start and finish Google sign-in through the HTTPS origin. Do not mix it with