cartethyia 2.7.3 → 2.7.5

package/src/console/api-keys/contracts.ts

@@ -8,11 +8,12 @@ import { randomBytes } from "node:crypto";
 import type { ApiKeyRecord, ApiKeyStore } from "../../persistence/stores/api-key-store";
 import { hashSecret } from "../../security/crypto";
 import { type ShareLinkStore, type ShareLinkSummary } from "../../persistence/stores/share-store";
-import { API_KEY_MODES, type ApiKeyMode, type ApiKeyModelAccessMode, type ShareLinkKind } from "../../persistence/schema";
+import { API_KEY_MODES, API_KEY_CONCURRENCY_SCOPES, type ApiKeyMode, type ApiKeyModelAccessMode, type ShareLinkKind } from "../../persistence/schema";
 import { isValidTenantKeyScope, type AccessScope } from "../../security/access-control";
 import { normalizeClientRouterId } from "../../security/client-router-fingerprint";
 import type { ShareActivityPort } from "../share/share-usage";
 import { ConsoleDomainError } from "../shared/errors";
+import { pickDefined } from "../shared/object";
 import type { ConsoleAccessResolver } from "../auth/access";
 import type { ApiKeyAdmissionService } from "../../security/admission/service";
 import {
@@ -34,6 +35,9 @@ export type {
   SharedKeySummary,
   SharedKeyActivityDetail,
 } from "../share/share-usage";
+/** How a share template's concurrency cap applies to its recipients. */
+export type ConcurrencyScope = (typeof API_KEY_CONCURRENCY_SCOPES)[number];
+
 /** Input accepted when creating or editing a key. Null limits mean unlimited. */
 export interface CreateApiKeyRequest {
   enabled?: boolean;
@@ -49,6 +53,13 @@ export interface CreateApiKeyRequest {
   monthlyTokenLimit?: number | null;
   lifetimeTokenBudget?: number | null;
   maxConcurrentRequests?: number | null;
+  /**
+   * How `maxConcurrentRequests` applies to a share template's family:
+   * `family` (default) = one cap across all recipient keys (a single shared
+   * admission counter); `per_key` = each recipient key gets its own cap and
+   * independent counter. Ignored/meaningless for personal keys.
+   */
+  concurrencyScope?: ConcurrencyScope;
   /** Share-template slot cap; only meaningful when keyMode === "share". */
   maxChildren?: number | null;
   modelPrefix?: string;
@@ -90,6 +101,7 @@ export interface ApiKeyResponse {
   readonly modelList?: readonly string[];
   readonly clientRouterDenylist?: readonly string[];
   readonly maxConcurrentRequests?: number;
+  readonly concurrencyScope?: ConcurrencyScope;
   readonly maxChildren?: number;
   readonly notesTitle?: string;
   readonly notesSubtitle?: string;
@@ -101,6 +113,11 @@ export interface ApiKeyResponse {
   readonly sharePopupBody?: string;
   readonly createdAt: string;
   readonly revokedAt?: string;
+  /** Ban state; see the schema columns for the contract. */
+  readonly bannedAt?: string;
+  readonly banReason?: string;
+  /** When the ban lifts on its own; absent means permanent. */
+  readonly bannedUntil?: string;
   readonly tokensConsumed: number;
 }
 /** Creation result; plaintext is returned only when a personal key is minted. */
@@ -113,6 +130,31 @@ export interface UpdateApiKeyResponse extends ApiKeyResponse {
   readonly secret?: string;
 }
 
+/**
+ * Ban reasons offered by the console dropdown, and the durations the ban
+ * endpoint accepts. These are pure lists, kept in `ban-constants.ts` (no
+ * `node:*` imports) so the dashboard can import them without dragging Node
+ * crypto into the browser bundle. Re-exported here for backend consumers
+ * (`routes.ts` validates against `BAN_DURATION_CHOICES`).
+ */
+export {
+  API_KEY_BAN_REASONS,
+  BAN_DURATION_CHOICES,
+} from "./ban-constants";
+
+/** What a bare "ban this key" click uses: the shortest, most reversible choice. */
+export const DEFAULT_BAN_MINUTES: number = 60;
+
+/** Body accepted by the ban endpoint. */
+export interface BanApiKeyRequest {
+  readonly reason: string;
+  /**
+   * Ban duration in whole minutes from {@link BAN_DURATION_CHOICES}; `null`
+   * means permanent. Absent = {@link DEFAULT_BAN_MINUTES}.
+   */
+  readonly minutes?: number | null;
+}
+
 /** API-key route dependency boundary. */
 export interface ApiKeyConfig {
   readonly store: ApiKeyStore;
@@ -206,16 +248,20 @@ export function generateApiKeySecret(prefix = DEFAULT_API_KEY_PREFIX): {
   return { secret, hash: hashSecret(secret), prefix };
 }
 
-/** Normalizes a caller-supplied prefix; falls back to the default. */
-export function resolveKeyPrefix(raw: string | undefined): string {
+/** Normalizes a caller-supplied prefix; falls back to `fallback`. */
+function resolvePrefix(raw: string | undefined, fallback: string): string {
   const trimmed = raw?.trim();
-  return trimmed && trimmed.length > 0 ? trimmed : DEFAULT_API_KEY_PREFIX;
+  return trimmed && trimmed.length > 0 ? trimmed : fallback;
+}
+
+/** Normalizes a caller-supplied prefix; falls back to the personal default. */
+export function resolveKeyPrefix(raw: string | undefined): string {
+  return resolvePrefix(raw, DEFAULT_API_KEY_PREFIX);
 }
 
-/** Resolves the share-key prefix; falls back to the default. */
+/** Resolves the share-key prefix; falls back to the share default. */
 export function resolveShareKeyPrefix(raw: string | undefined): string {
-  const trimmed = raw?.trim();
-  return !trimmed ? DEFAULT_SHARE_API_KEY_PREFIX : trimmed;
+  return resolvePrefix(raw, DEFAULT_SHARE_API_KEY_PREFIX);
 }
 
 /** Maximum hint the enroll page accepts; the dashboard caps its input there. */
@@ -300,6 +346,19 @@ export function validateApiKeyRequest(request: CreateApiKeyRequest): readonly Ac
   finitePositive(request.monthlyTokenLimit, "monthlyTokenLimit");
   finitePositive(request.lifetimeTokenBudget, "lifetimeTokenBudget");
   finitePositive(request.maxConcurrentRequests, "maxConcurrentRequests");
+  if (
+    request.concurrencyScope !== undefined &&
+    !(API_KEY_CONCURRENCY_SCOPES as readonly string[]).includes(request.concurrencyScope)
+  ) {
+    throw new ConsoleDomainError("invalid_limits", 400, "concurrencyScope must be family or per_key");
+  }
+  if (request.concurrencyScope !== undefined && keyMode !== "share") {
+    throw new ConsoleDomainError(
+      "invalid_limits",
+      400,
+      "concurrencyScope is only valid for share templates",
+    );
+  }
   if (request.maxChildren !== undefined && request.maxChildren !== null) {
     finitePositive(request.maxChildren, "maxChildren");
     if (request.maxChildren > 10_000) {
@@ -375,31 +434,33 @@ export function sanitizeApiKeyResponse(record: ApiKeyRecord): ApiKeyResponse {
      * renaming the key cannot change which key is the default.
      */
     isDefault: isDefaultGatewayApiKey(record),
-    ...(keyPrefix === undefined ? {} : { keyPrefix }),
-    ...(record.parentKeyId === undefined ? {} : { parentKeyId: record.parentKeyId }),
-    ...(record.notesTitle === undefined ? {} : { notesTitle: record.notesTitle }),
-    ...(record.notesSubtitle === undefined ? {} : { notesSubtitle: record.notesSubtitle }),
-    ...(record.notesBody === undefined ? {} : { notesBody: record.notesBody }),
-    ...(record.sharePopupEnabled === undefined ? {} : { sharePopupEnabled: record.sharePopupEnabled }),
-    ...(record.sharePopupImageMime === undefined
-      ? {}
-      : { sharePopupImageMime: record.sharePopupImageMime }),
-    ...(record.sharePopupTitle === undefined ? {} : { sharePopupTitle: record.sharePopupTitle }),
-    ...(record.sharePopupBody === undefined ? {} : { sharePopupBody: record.sharePopupBody }),
-    ...(record.requestsPerMinute === undefined ? {} : { requestsPerMinute: record.requestsPerMinute }),
-    ...(record.dailyTokenLimit === undefined ? {} : { dailyTokenLimit: record.dailyTokenLimit }),
-    ...(record.monthlyTokenLimit === undefined ? {} : { monthlyTokenLimit: record.monthlyTokenLimit }),
-    ...(record.lifetimeTokenBudget === undefined ? {} : { lifetimeTokenBudget: record.lifetimeTokenBudget }),
-    ...(record.maxConcurrentRequests === undefined ? {} : { maxConcurrentRequests: record.maxConcurrentRequests }),
-    ...(record.maxChildren === undefined ? {} : { maxChildren: record.maxChildren }),
-    ...(record.modelPrefix === undefined ? {} : { modelPrefix: record.modelPrefix }),
-    ...(record.modelAccessMode === undefined ? {} : { modelAccessMode: record.modelAccessMode }),
-    ...(record.modelList === undefined ? {} : { modelList: record.modelList }),
-    ...(record.clientRouterDenylist === undefined
-      ? {}
-      : { clientRouterDenylist: record.clientRouterDenylist }),
+    ...pickDefined({
+      keyPrefix,
+      parentKeyId: record.parentKeyId,
+      notesTitle: record.notesTitle,
+      notesSubtitle: record.notesSubtitle,
+      notesBody: record.notesBody,
+      sharePopupEnabled: record.sharePopupEnabled,
+      sharePopupImageMime: record.sharePopupImageMime,
+      sharePopupTitle: record.sharePopupTitle,
+      sharePopupBody: record.sharePopupBody,
+      requestsPerMinute: record.requestsPerMinute,
+      dailyTokenLimit: record.dailyTokenLimit,
+      monthlyTokenLimit: record.monthlyTokenLimit,
+      lifetimeTokenBudget: record.lifetimeTokenBudget,
+      maxConcurrentRequests: record.maxConcurrentRequests,
+      concurrencyScope: record.concurrencyScope,
+      maxChildren: record.maxChildren,
+      modelPrefix: record.modelPrefix,
+      modelAccessMode: record.modelAccessMode,
+      modelList: record.modelList,
+      clientRouterDenylist: record.clientRouterDenylist,
+      revokedAt: record.revokedAt?.toISOString(),
+      bannedAt: record.bannedAt?.toISOString(),
+      banReason: record.banReason,
+      bannedUntil: record.bannedUntil?.toISOString(),
+    }),
     createdAt: record.createdAt.toISOString(),
-    ...(record.revokedAt === undefined ? {} : { revokedAt: record.revokedAt.toISOString() }),
     tokensConsumed: record.tokensConsumed,
   };
 }

package/src/console/api-keys/routes.ts

@@ -2,7 +2,7 @@
 //
 // Owns validation, CRUD operations, and route wiring through the ApiKeyStore.
 
-import { Elysia, t } from "elysia";
+import { Elysia, t, type AnyElysia } from "elysia";
 import { randomBytes, randomUUID } from "node:crypto";
 import { decryptCredentialToString, encryptCredential } from "../../security/crypto";
 import { invalidateApiKeyCache } from "../../security/api-key-auth";
@@ -11,8 +11,8 @@ import { generateShareSlug, hashShareToken } from "../../persistence/stores/shar
 import type { AccessDecision } from "../../security/access-control";
 import { ConsoleDomainError, errorResponse, requireTenantScope } from "../shared/errors";
 import { literalUnion } from "../shared/elysia-schema";
-import { API_KEY_MODES, API_KEY_MODEL_ACCESS_MODES, type ShareLinkKind } from "../../persistence/schema";
-import type { ApiKeyConfig, ApiKeyResponse, UpdateApiKeyResponse } from "./contracts";
+import { API_KEY_MODES, API_KEY_MODEL_ACCESS_MODES, API_KEY_CONCURRENCY_SCOPES, type ShareLinkKind } from "../../persistence/schema";
+import type { ApiKeyConfig, ApiKeyResponse, BanApiKeyRequest, UpdateApiKeyResponse } from "./contracts";
 import type {
   ApiKeyPatch,
   ApiKeyRecord,
@@ -20,6 +20,9 @@ import type {
   SharedChildrenPageOptions,
 } from "../../persistence/stores/api-key-store";
 import {
+  API_KEY_BAN_REASONS,
+  BAN_DURATION_CHOICES,
+  DEFAULT_BAN_MINUTES,
   generateApiKeySecret,
   isDefaultGatewayApiKey,
   parseSharePopupImage,
@@ -38,6 +41,7 @@ import {
 } from "./contracts";
 import type { SharedKeyActivityDetail, SharedKeySummary } from "../share/share-usage";
 import { popupImageBytes } from "./share-popup-image";
+import { log } from "../../observability/logger";
 
 const SHARED_CHILD_SORT_COLUMNS = new Set<SharedChildSortColumn>([
   "createdAt",
@@ -48,6 +52,9 @@ const SHARED_CHILD_SORT_COLUMNS = new Set<SharedChildSortColumn>([
   "enabled",
 ]);
 
+/** The offered ban durations as a set of minute values, hoisted once. */
+const BAN_DURATION_MINUTES = new Set(BAN_DURATION_CHOICES.map((choice) => choice.minutes));
+
 /** Parses and bounds the paginated share-child list query. */
 function parseSharedChildrenQuery(query: URLSearchParams): SharedChildrenPageOptions {
   const limitRaw = query.get("limit");
@@ -93,7 +100,16 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
             if (record.keyMode !== "share") return response;
             const family = await config.store
               .sumFamilyTelemetryConsumed(authorized.tenantId, record.id)
-              .catch(() => 0);
+              .catch((error) => {
+                // A failed sum must not fail the whole list, but it must not
+                // be silent either: reporting the share template's spend as 0
+                // under-reports consumed tokens in the console list.
+                log.warn(
+                  `[api-keys] sumFamilyTelemetryConsumed failed for key ${record.id}; reporting 0`,
+                  error as Error,
+                );
+                return 0;
+              });
             return { ...response, tokensConsumed: response.tokensConsumed + family };
           }),
         );
@@ -185,6 +201,7 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
         ...(request.monthlyTokenLimit == null ? {} : { monthlyTokenLimit: request.monthlyTokenLimit }),
         ...(request.lifetimeTokenBudget == null ? {} : { lifetimeTokenBudget: request.lifetimeTokenBudget }),
         ...(request.maxConcurrentRequests == null ? {} : { maxConcurrentRequests: request.maxConcurrentRequests }),
+        ...(request.concurrencyScope !== undefined ? { concurrencyScope: request.concurrencyScope } : {}),
         ...(request.maxChildren == null ? {} : { maxChildren: request.maxChildren }),
         ...(request.modelPrefix === undefined ? {} : { modelPrefix: request.modelPrefix }),
         modelAccessMode: request.modelAccessMode ?? "whitelist",
@@ -320,6 +337,7 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
         ...(patchRequest.monthlyTokenLimit === undefined ? {} : { monthlyTokenLimit: patchRequest.monthlyTokenLimit }),
         ...(patchRequest.lifetimeTokenBudget === undefined ? {} : { lifetimeTokenBudget: patchRequest.lifetimeTokenBudget }),
         ...(patchRequest.maxConcurrentRequests === undefined ? {} : { maxConcurrentRequests: patchRequest.maxConcurrentRequests }),
+        ...(patchRequest.concurrencyScope !== undefined ? { concurrencyScope: patchRequest.concurrencyScope } : {}),
         ...(patchRequest.maxChildren === undefined ? {} : { maxChildren: patchRequest.maxChildren }),
         ...(patchRequest.modelPrefix === undefined ? {} : { modelPrefix: patchRequest.modelPrefix }),
         ...(patchRequest.modelAccessMode === undefined ? {} : { modelAccessMode: patchRequest.modelAccessMode }),
@@ -775,6 +793,86 @@ export function createApiKeyOperations(config: ApiKeyConfig) {
       });
       return { success: true };
     },
+    async banKey(
+      access: AccessDecision | undefined,
+      keyId: string,
+      request: BanApiKeyRequest,
+    ): Promise<ApiKeyResponse> {
+      const authorized = requireTenantScope(access, "dashboard:write");
+      const reason = request.reason.trim();
+      if (reason.length === 0)
+        throw new ConsoleDomainError("invalid_request", 400, "reason is required");
+      // Parse the duration choice. `null` is permanent; absent defaults to one
+      // hour. Anything not on the offered list is rejected rather than clamped —
+      // clamping would answer a request for 90 days with a week and report
+      // success.
+      const chosenMinutes = request.minutes === undefined ? DEFAULT_BAN_MINUTES : request.minutes;
+      if (!BAN_DURATION_MINUTES.has(chosenMinutes)) {
+        throw new ConsoleDomainError(
+          "invalid_request",
+          400,
+          "Unsupported ban duration. Choose one of the offered durations.",
+        );
+      }
+      const bannedUntil = chosenMinutes === null ? null : new Date(Date.now() + chosenMinutes * 60_000);
+      const current = await config.store.get(authorized.tenantId, keyId);
+      if (!current || current.revokedAt !== undefined)
+        throw new ConsoleDomainError("key_not_found", 404, "Key not found");
+      const banned = await config.store.ban(authorized.tenantId, keyId, reason, bannedUntil);
+      if (!banned) throw new ConsoleDomainError("key_not_found", 404, "Key not found");
+      // A banned child key does not affect its share template or sibling keys:
+      // `store.ban` only turns off the one row named by `keyId`, and the auth
+      // path rejects per key hash. The template keeps issuing working children.
+      // A banned key must leave the auth cache for every process at once.
+      invalidateApiKeyCache();
+      await config.auditSink?.record({
+        access: authorized,
+        action: "api_key.banned",
+        target: keyId,
+        detail: {
+          reason,
+          // The human-readable label is derived server-side from the machine
+          // `reason`, so the audit trail cannot be skewed by a client-authored
+          // label. Unknown reasons (custom text) simply carry no label; the
+          // free-text `reason` above is still recorded verbatim.
+          ...(API_KEY_BAN_REASONS.find((r) => r.value === reason)?.label === undefined
+            ? {}
+            : { reasonLabel: API_KEY_BAN_REASONS.find((r) => r.value === reason)!.label }),
+          ...(bannedUntil === null ? { permanent: true } : { bannedUntil: bannedUntil.toISOString() }),
+        },
+      });
+      // The ban mutates the row already fetched; derive the response from that
+      // record instead of re-fetching after the write. Match the store's own
+      // mapping: a `null` (permanent) `bannedUntil` is omitted, not carried.
+      return sanitizeApiKeyResponse({
+        ...current,
+        bannedAt: new Date(),
+        banReason: reason,
+        ...(bannedUntil ? { bannedUntil } : {}),
+      });
+    },
+    async unbanKey(
+      access: AccessDecision | undefined,
+      keyId: string,
+    ): Promise<ApiKeyResponse> {
+      const authorized = requireTenantScope(access, "dashboard:write");
+      const current = await config.store.get(authorized.tenantId, keyId);
+      if (!current || current.revokedAt !== undefined)
+        throw new ConsoleDomainError("key_not_found", 404, "Key not found");
+      const unbanned = await config.store.unban(authorized.tenantId, keyId);
+      if (!unbanned) throw new ConsoleDomainError("key_not_found", 404, "Key not found");
+      invalidateApiKeyCache();
+      await config.auditSink?.record({
+        access: authorized,
+        action: "api_key.unbanned",
+        target: keyId,
+      });
+      // Unban clears all three ban columns and re-enables the key; derive the
+      // response from the pre-fetch instead of re-fetching after the write.
+      const { bannedAt: _bannedAt, banReason: _banReason, bannedUntil: _bannedUntil, ...currentRest } = current;
+      const unbannedRecord: ApiKeyRecord = { ...currentRest, enabled: true };
+      return sanitizeApiKeyResponse(unbannedRecord);
+    },
   };
   return operations;
 }
@@ -793,6 +891,7 @@ const apiKeyBody = t.Object({
   monthlyTokenLimit: t.Optional(t.Union([t.Number(), t.Null()])),
   lifetimeTokenBudget: t.Optional(t.Union([t.Number(), t.Null()])),
   maxConcurrentRequests: t.Optional(t.Union([t.Number(), t.Null()])),
+  concurrencyScope: t.Optional(literalUnion(API_KEY_CONCURRENCY_SCOPES)),
   modelPrefix: t.Optional(t.String()),
   modelAccessMode: t.Optional(literalUnion(API_KEY_MODEL_ACCESS_MODES)),
   modelList: t.Optional(t.Array(t.String())),
@@ -830,7 +929,7 @@ function jsonNull(): Response {
   });
 }
 /** Creates tenant-bound API-key routes with request-local authorization. */
-export function createApiKeyRoutes(config: ApiKeyConfig): Elysia {
+export function createApiKeyRoutes(config: ApiKeyConfig): AnyElysia {
   const factory = createApiKeyOperations(config);
   return new Elysia({ prefix: "/api-keys" })
     .get("/", async ({ request, set }) => {
@@ -950,6 +1049,32 @@ export function createApiKeyRoutes(config: ApiKeyConfig): Elysia {
         return errorResponse(error, set, "API-key operation failed");
       }
     })
+    .post(
+      "/:keyId/ban",
+      {
+        body: t.Object({
+          reason: t.String(),
+          // `reasonLabel` is deliberately not accepted: the audit label is
+          // derived server-side from `reason` (see `banKey`), so a client
+          // cannot author the human-readable audit entry.
+          minutes: t.Optional(t.Union([t.Number({ minimum: 1 }), t.Null()])),
+        }),
+      },
+      async ({ request, params, body, set }) => {
+        try {
+          return await factory.banKey(config.accessResolver(request), params.keyId, body);
+        } catch (error) {
+          return errorResponse(error, set, "API-key operation failed");
+        }
+      },
+    )
+    .post("/:keyId/unban", async ({ request, params, set }) => {
+      try {
+        return await factory.unbanKey(config.accessResolver(request), params.keyId);
+      } catch (error) {
+        return errorResponse(error, set, "API-key operation failed");
+      }
+    })
     .get("/:keyId/share", async ({ request, params, set }) => {
       try {
         const share = await factory.getShare(config.accessResolver(request), params.keyId, {
@@ -988,5 +1113,5 @@ export function createApiKeyRoutes(config: ApiKeyConfig): Elysia {
       } catch (error) {
         return errorResponse(error, set, "API-key operation failed");
       }
-    }) as unknown as Elysia;
+    });
 }

package/src/console/audit/routes.ts

@@ -1,4 +1,4 @@
-import { Elysia, t } from "elysia";
+import { Elysia, t, type AnyElysia } from "elysia";
 import { errorResponse, requireGlobalAdmin, requireTenantScope } from "../shared/errors";
 import { parseQueryLimit } from "../shared/query";
 import type { AuditRoutesConfig } from "./contracts";
@@ -10,7 +10,7 @@ const listQuery = t.Object({
   actor: t.Optional(t.String()),
 });
 
-export function createAuditRoutes(config: AuditRoutesConfig): Elysia {
+export function createAuditRoutes(config: AuditRoutesConfig): AnyElysia {
   return new Elysia().get("/audit", { query: listQuery }, async ({ request, query, set }) => {
     try {
       const resolved = config.accessResolver(request);
@@ -28,5 +28,5 @@ export function createAuditRoutes(config: AuditRoutesConfig): Elysia {
     } catch (e) {
       return errorResponse(e, set, "Audit read failed");
     }
-  }) as unknown as Elysia;
+  });
 }

package/src/console/auth/access.ts

@@ -1,4 +1,4 @@
-import type { AccessDecision } from "../../security/access-control";
-
-/** Resolves the authenticated console request to a tenant-scoped decision. */
-export type ConsoleAccessResolver = (request: Request) => AccessDecision | undefined;
+import type { AccessDecision } from "../../security/access-control";
+
+/** Resolves the authenticated console request to a tenant-scoped decision. */
+export type ConsoleAccessResolver = (request: Request) => AccessDecision | undefined;

package/src/console/auth/account-reset.ts

@@ -25,7 +25,7 @@
 import { GatewayError } from "../../protocol/gateway-error";
 import { isLoopbackPeer, tokenMatches } from "../../transport/drain-endpoint";
 
-export interface ConsoleAccountResetDeps {
+interface ConsoleAccountResetDeps {
   /** Shared secret; the route is registered only when this is set. */
   readonly token: string;
   /** Removes every console user and session. Resolves to the number removed. */
@@ -42,12 +42,12 @@ export function createConsoleAccountResetHandler(
   return async ({ request, body }) => {
     if (!isLoopbackPeer(deps.resolvePeerAddress(request)))
       throw new GatewayError(
-        "invalid_request",
+        "policy_rejected",
         403,
-        "console account reset is only available from loopback",
+        "console account reset is only available from loopback (request {requestId}). This operation is only allowed from a trusted loopback connection — no hard feelings 🫂",
       );
     if (!tokenMatches(request.headers.get("x-drain-token"), deps.token))
-      throw new GatewayError("invalid_request", 401, "invalid reset token");
+      throw new GatewayError("authentication_failed", 401, "invalid reset token (request {requestId}). Wrong key, right door — check the token 🔑");
     const confirm =
       body !== null && typeof body === "object" && "confirm" in body
         ? body.confirm
@@ -56,7 +56,7 @@ export function createConsoleAccountResetHandler(
       throw new GatewayError(
         "invalid_request",
         400,
-        `send {"confirm":"${CONFIRMATION}"} to confirm; this deletes every console account`,
+        `send {"confirm":"${CONFIRMATION}"} to confirm (request {requestId}); this deletes every console account. Make sure you mean it — there's no undo 🫂`,
       );
 
     const removed = await deps.resetConsoleAccount();

package/src/console/auth/audit-recorder.ts

@@ -8,7 +8,7 @@ import {
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import { type AccessDecision } from "../../security/access-control";
 
-export interface AuditRecordInput {
+interface AuditRecordInput {
   readonly access: AccessDecision;
   readonly action: string;
   readonly target: string;

package/src/console/auth/lockout.ts

@@ -7,8 +7,9 @@ import {
 } from "../../persistence/schema";
 
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
+import { log } from "../../observability/logger";
 
-export class ConsoleLockoutStore {
+class ConsoleLockoutStore {
   constructor(private readonly db: CartethyiaDatabase) {}
 
   async getLockedUntil(ip: string): Promise<Date | null | undefined> {
@@ -143,8 +144,11 @@ export class ConsoleLockoutService {
           enforcement: "full_network_lockout",
         },
       });
-    } catch {
-      // Best-effort audit logging; the ban itself remains enforced via the DB row.
+    } catch (error) {
+      // Best-effort audit logging; the ban itself remains enforced via the DB
+      // row. A failed write is logged — for a security-relevant event
+      // (`security.ip_banned`) total silence would hide a broken audit trail.
+      log.error(`[auth] failed to record ip_banned audit for ${ip}`, error as Error, reason);
     }
   }
 

package/src/console/auth/row-coercion.ts

@@ -3,7 +3,7 @@ import type { ConsoleSession, ConsoleUser } from "../../persistence/schema";
 
 import { isRecord } from "../../protocol/codecs";
 
-export function asDate(value: unknown): Date | undefined {
+function asDate(value: unknown): Date | undefined {
   if (value instanceof Date && !Number.isNaN(value.getTime())) return value;
   if (typeof value === "string" || typeof value === "number") {
     const date = new Date(value);
@@ -14,33 +14,78 @@ export function asDate(value: unknown): Date | undefined {
 
 export function sessionRecord(value: unknown): ConsoleSession | undefined {
   if (!isRecord(value)) return undefined;
+  const id = value.id;
+  const userId = value.userId;
+  const sessionToken = value.sessionToken;
+  const ipAddress = value.ipAddress;
+  const userAgent = value.userAgent;
   if (
-    typeof value.id !== "string" ||
-    typeof value.userId !== "string" ||
-    typeof value.sessionToken !== "string"
+    typeof id !== "string" ||
+    typeof userId !== "string" ||
+    typeof sessionToken !== "string"
   ) {
     return undefined;
   }
   const expiresAt = asDate(value.expiresAt);
   const createdAt = asDate(value.createdAt);
   if (!expiresAt || !createdAt) return undefined;
-  return { ...value, expiresAt, createdAt } as unknown as ConsoleSession;
+  // Construct the result explicitly field-by-field so the output shape is
+  // exactly what was validated — arbitrary extra keys on a driver row must
+  // not survive into the typed session.
+  return {
+    id,
+    userId,
+    sessionToken,
+    ...(ipAddress === null || typeof ipAddress === "string" ? { ipAddress } : { ipAddress: null }),
+    ...(userAgent === null || typeof userAgent === "string" ? { userAgent } : { userAgent: null }),
+    expiresAt,
+    createdAt,
+  };
 }
 
 export function userRecord(value: unknown): ConsoleUser | undefined {
   if (!isRecord(value)) return undefined;
+  const id = value.id;
+  const username = value.username;
+  const passwordHash = value.passwordHash;
+  const isActive = value.isActive;
   if (
-    typeof value.id !== "string" ||
-    typeof value.username !== "string" ||
-    typeof value.passwordHash !== "string" ||
-    typeof value.isActive !== "boolean"
+    typeof id !== "string" ||
+    typeof username !== "string" ||
+    typeof passwordHash !== "string" ||
+    typeof isActive !== "boolean"
   ) {
     return undefined;
   }
-  return value as unknown as ConsoleUser;
+  // Timestamps are coerced through `asDate` because SQLite hands them back as
+  // text; a login path that rejects non-Date values must still work there.
+  const createdAt = asDate(value.createdAt);
+  const updatedAt = asDate(value.updatedAt);
+  if (!createdAt || !updatedAt) return undefined;
+  const tenantId = value.tenantId;
+  const email = value.email;
+  const displayName = value.displayName;
+  const isFirstBoot = value.isFirstBoot;
+  const isPlatformAdmin = value.isPlatformAdmin;
+  // Construct the result explicitly field-by-field so the output shape is
+  // exactly what was validated — arbitrary extra keys on a driver row must
+  // not survive into the typed user.
+  return {
+    id,
+    tenantId: typeof tenantId === "string" ? tenantId : "",
+    username,
+    email: typeof email === "string" ? email : null,
+    passwordHash,
+    displayName: typeof displayName === "string" ? displayName : null,
+    isActive,
+    isPlatformAdmin: isPlatformAdmin === true,
+    isFirstBoot: isFirstBoot === true,
+    createdAt,
+    updatedAt,
+  };
 }
 
-export function mutationAffectedRows(value: unknown): number | undefined {
+function mutationAffectedRows(value: unknown): number | undefined {
   if (!isRecord(value)) return undefined;
   for (const key of ["rowCount", "rowsAffected", "changes"] as const) {
     const count = value[key];
@@ -50,7 +95,7 @@ export function mutationAffectedRows(value: unknown): number | undefined {
 }
 
 /** Awaitable Drizzle mutation builder that may expose `.returning()`. */
-export interface ReturningBuilder extends PromiseLike<unknown> {
+interface ReturningBuilder extends PromiseLike<unknown> {
   returning?: (...columns: unknown[]) => PromiseLike<unknown[]>;
 }
 

package/src/console/auth/session-resolver.ts

@@ -45,7 +45,7 @@ export async function resolveConsoleAccess(
 }
 
 /** The signed-in console user behind a request, or `null` when unauthenticated. */
-export interface ResolvedConsoleUser {
+interface ResolvedConsoleUser {
   readonly id: string;
   readonly sessionId: string;
   readonly tenantId: string;

package/src/console/auth/session-service.ts

@@ -58,7 +58,7 @@ function newSessionToken(): string {
   return randomBytes(32).toString("base64url");
 }
 
-export class ConsoleSessionStore {
+class ConsoleSessionStore {
   constructor(private readonly db: CartethyiaDatabase) {}
 
   async create(newSession: {
@@ -73,7 +73,13 @@ export class ConsoleSessionStore {
     const inserted = await returningRows(this.db.insert(consoleSessions).values(newSession));
     assertMutationApplied(inserted, "Console session");
     const persisted = sessionRecord(inserted.rows[0]);
-    return persisted ?? ({ ...newSession } as unknown as ConsoleSession);
+    if (!persisted) {
+      // `assertMutationApplied` already refused a failed insert, so an
+      // unshaped row here is a driver/schema mismatch — pretending success by
+      // returning the input cast to ConsoleSession would mask it.
+      throw new Error("Console session row could not be coerced after insert");
+    }
+    return persisted;
   }
 
   async findValidByTokenHash(tokenHash: string, now: Date): Promise<ConsoleSession | null> {