bazis 0.98.24 → 0.98.26

package/core/http/Authorization/authorizeComposer.ts

@@ -1,4 +1,5 @@
-import { ForbiddenError } from "../Errors/HttpError";
+import { JwtError } from "../../../library/jwt/errors";
+import { ForbiddenError, UnauthorizedError } from "../Errors/HttpError";
 import type { HttpMiddleware } from "../Middleware/types";
 import type { RouteMiddlewareComposer } from "../options";
 import { resolveAuthorizeMeta } from "./metadata";
@@ -8,7 +9,8 @@ import { resolveAuthorizeMeta } from "./metadata";
  * the per-route composers. For routes that require authorization it returns
  * middleware that runs all checks in order: any that returns `false` → `403`;
  * a check may throw an `HttpError` itself (for example
- * `UnauthorizedError` → `401`).
+ * `UnauthorizedError` → `401`). A `JwtError` (missing, malformed, expired or
+ * forged token) escaping a check is a 401 as well, not a server error.
  */
 export function createAuthorizeComposer(): RouteMiddlewareComposer {
   return (controllerClass, methodName) => {
@@ -20,7 +22,18 @@ export function createAuthorizeComposer(): RouteMiddlewareComposer {
     const { checks } = meta.authorize;
     const middleware: HttpMiddleware = async (ctx, next) => {
       for (const check of checks) {
-        if (!(await check(ctx))) {
+        let allowed: boolean;
+        try {
+          allowed = await check(ctx);
+        } catch (error) {
+          if (error instanceof JwtError) {
+            const unauthorized = new UnauthorizedError();
+            Object.defineProperty(unauthorized, "cause", { value: error, configurable: true, writable: true });
+            throw unauthorized;
+          }
+          throw error;
+        }
+        if (!allowed) {
           throw new ForbiddenError();
         }
       }

package/core/http/Authorization/bearerToken.ts

@@ -0,0 +1,11 @@
+import type { HttpContext } from "../HttpContext/HttpContext";
+
+/**
+ * The token of an `Authorization: Bearer <token>` header, or `undefined`
+ * without the header, with another scheme or with an empty token. The scheme
+ * is case-insensitive (RFC 7235); surrounding spaces are trimmed.
+ */
+export function bearerToken(ctx: Pick<HttpContext, "header">): string | undefined {
+  const match = /^\s*bearer\s+(\S+)\s*$/i.exec(ctx.header("authorization") ?? "");
+  return match?.[1];
+}

package/core/http/Middleware/errorHandler.ts

@@ -19,6 +19,13 @@ export interface ErrorHandlerOptions {
   onUnexpectedError?: (ctx: HttpContext, error: unknown) => void;
   /** Replaces the built-in logging of unexpected errors. */
   logError?: (error: unknown) => void;
+  /**
+   * Status for a non-{@link HttpError} failure, for example
+   * `databaseErrorStatus` from `bazis/core/orm`; `undefined` keeps 500. The
+   * body stays the standard reason phrase. A mapped 4xx is the client's
+   * mistake and is not logged or sent to `onUnexpectedError`.
+   */
+  status?: (error: unknown) => number | undefined;
   /**
    * Logger for unexpected errors when {@link logError} is absent: one `error`
    * line with the method, path, request id and the redacted error. The server
@@ -124,8 +131,8 @@ export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware
         );
         return;
       }
-      safelyReportUnexpected(options, log, ctx, error);
-      const [status, title] = unexpectedStatus(error);
+      const [status, title] = unexpectedStatus(error, options.status);
+      if (status >= 500) safelyReportUnexpected(options, log, ctx, error);
       ctx.response = options.exposeDetails
         ? safeJsonResponse(status, {
             error: title,
@@ -146,9 +153,17 @@ export function errorHandler(options: ErrorHandlerOptions = {}): HttpMiddleware
  * and stays 500, like everything else. Upstream details never reach the
  * client; the log keeps the full error.
  */
-function unexpectedStatus(error: unknown): readonly [number, string] {
+const REASONS: Readonly<Record<number, string>> = {
+  400: "Bad Request", 404: "Not Found", 409: "Conflict", 410: "Gone", 412: "Precondition Failed", 422: "Unprocessable Content",
+  423: "Locked", 429: "Too Many Requests", 500: "Internal Server Error", 502: "Bad Gateway", 503: "Service Unavailable", 504: "Gateway Timeout",
+};
+
+function unexpectedStatus(error: unknown, mapper?: (error: unknown) => number | undefined): readonly [number, string] {
   if (error instanceof HttpClientError && error.code !== undefined) {
     return error.code === HttpErrorCode.Timeout ? [504, "Gateway Timeout"] : [502, "Bad Gateway"];
   }
+  let mapped: number | undefined;
+  try { mapped = mapper?.(error); } catch { mapped = undefined; }
+  if (mapped !== undefined && Number.isInteger(mapped) && mapped >= 400 && mapped <= 599) return [mapped, REASONS[mapped] ?? (mapped >= 500 ? "Server Error" : "Client Error")];
   return [500, "Internal Server Error"];
 }

package/core/http/index.ts

@@ -34,6 +34,7 @@ export { PRINCIPAL_STATE_KEY, type RequestPrincipal } from "./HttpContext/princi
 // Authorization
 export { Authorize, AllowAnonymous } from "./Authorization/Authorize";
 export { createAuthorizeComposer } from "./Authorization/authorizeComposer";
+export { bearerToken } from "./Authorization/bearerToken";
 export {
   resolveAuthorizeMeta,
   type AuthorizeCheck,

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.24" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.98.26" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/core/orm/databaseErrorStatus.ts

@@ -0,0 +1,35 @@
+import {
+  CheckViolationError,
+  EntityNotFoundError,
+  ForeignKeyViolationError,
+  LockTimeoutError,
+  NotNullViolationError,
+  OrmTransactionScopeError,
+  OrmValidationError,
+  TransactionOutcomeUnknownError,
+  UniqueViolationError,
+} from "../../library/orm";
+
+/** SQLSTATEs a client may retry: serialization failure, deadlock, statement timeout. */
+const RETRYABLE = new Set(["40001", "40P01", "57014"]);
+
+/**
+ * HTTP status for a database error, for `http: { errorHandler: { status:
+ * databaseErrorStatus } }`: 409 for a unique or foreign key conflict, 422 for
+ * a check, not-null or entity validation failure, 404 for `first()` without a
+ * row, 503 when the database did not answer, a lock or the transaction timed
+ * out, or a retryable conflict happened. Anything else stays 500.
+ */
+export function databaseErrorStatus(error: unknown): number | undefined {
+  if (error instanceof UniqueViolationError || error instanceof ForeignKeyViolationError) return 409;
+  if (error instanceof CheckViolationError || error instanceof NotNullViolationError || error instanceof OrmValidationError) return 422;
+  if (error instanceof EntityNotFoundError) return 404;
+  if (error instanceof LockTimeoutError || error instanceof TransactionOutcomeUnknownError) return 503;
+  if (error instanceof OrmTransactionScopeError && / timed out after \d+ ms/.test(error.message)) return 503;
+  if (typeof error === "object" && error !== null) {
+    const { errno, code } = error as { errno?: unknown; code?: unknown };
+    if (typeof errno === "string" && RETRYABLE.has(errno)) return 503;
+    if (typeof code === "string" && code.startsWith("ERR_POSTGRES_CONNECTION")) return 503;
+  }
+  return undefined;
+}

package/core/orm/index.ts

@@ -10,6 +10,7 @@ export { OrmConnectionLifecycle, OrmLifecycle, OrmProviderReadyLifecycle } from
 export { IRepository, repositoryFor } from "./repository";
 export { registerRepositories } from "./registerRepositories";
 export { paginate, type PageResult } from "./listQuery";
+export { databaseErrorStatus } from "./databaseErrorStatus";
 
 import { registerModuleMetadataExpander, type BazisModuleRef } from "../di";
 import { OrmOwnedStoreAdmissionError, type DbContext } from "../../library/orm";

package/library/jwt/signing/Rs256Algorithm.ts

@@ -34,14 +34,19 @@ export class Rs256Algorithm implements SigningAlgorithm {
     if (keys === null || typeof keys !== "object" || Array.isArray(keys)) {
       throw new TypeError("RS256 key material must be an object");
     }
-    this.keys = Object.freeze({ ...keys });
     for (const field of ["publicKeyPem", "privateKeyPem", "keyId"] as const) {
-      const value = this.keys[field];
+      const value = keys[field];
       if (value === undefined && field !== "publicKeyPem") continue;
       if (typeof value !== "string" || value.length === 0) {
         throw new TypeError(`RS256 ${field} must be a non-empty string`);
       }
     }
+    // A wrong key format must fail here, at startup, not on the first sign-in.
+    this.keys = Object.freeze({
+      ...keys,
+      publicKeyPem: checkedPem("publicKeyPem", keys.publicKeyPem),
+      ...(keys.privateKeyPem === undefined ? {} : { privateKeyPem: checkedPem("privateKeyPem", keys.privateKeyPem) }),
+    });
     this.canSign = this.keys.privateKeyPem !== undefined;
     this.keyId = this.keys.keyId;
   }
@@ -78,13 +83,13 @@ export class Rs256Algorithm implements SigningAlgorithm {
     if (this.keys.privateKeyPem === undefined) {
       throw new Error("RS256 private key PEM is required for signing");
     }
-    const key = await crypto.subtle.importKey(
+    const key = await importKey("private", () => crypto.subtle.importKey(
       "pkcs8",
-      decodePemToBuffer(this.keys.privateKeyPem),
+      decodePemToBuffer(this.keys.privateKeyPem!),
       RSA_PARAMS,
       false,
       ["sign"],
-    );
+    ));
     return this.cachedPrivate = this.requireStrongKey(key);
   }
 
@@ -92,13 +97,13 @@ export class Rs256Algorithm implements SigningAlgorithm {
     if (this.cachedPublic !== undefined) {
       return this.cachedPublic;
     }
-    const key = await crypto.subtle.importKey(
+    const key = await importKey("public", () => crypto.subtle.importKey(
       "spki",
       decodePemToBuffer(this.keys.publicKeyPem),
       RSA_PARAMS,
       true,
       ["verify"],
-    );
+    ));
     return this.cachedPublic = this.requireStrongKey(key);
   }
 
@@ -112,6 +117,39 @@ export class Rs256Algorithm implements SigningAlgorithm {
   }
 }
 
+const PEM = /^-----BEGIN ([A-Z0-9 ]+)-----\n([\s\S]*?)\n?-----END \1-----$/;
+
+/**
+ * Normalizes and checks one PEM string: literal `\n` (a key stored on one line
+ * in .env or a CI secret) and CRLF become line breaks; the label must be the
+ * one Web Crypto imports (PKCS#8 private, SPKI public), with a fix otherwise.
+ */
+function checkedPem(field: "publicKeyPem" | "privateKeyPem", value: string): string {
+  // A backslash never occurs in base64 or PEM armor, so this cannot change a valid key.
+  const pem = value.replaceAll("\\n", "\n").replaceAll("\r\n", "\n").trim();
+  const expected = field === "publicKeyPem" ? "PUBLIC KEY" : "PRIVATE KEY";
+  const match = PEM.exec(pem);
+  const label = match?.[1] ?? /^-----BEGIN ([A-Z0-9 ]+)-----/.exec(pem)?.[1];
+  if (label === undefined) throw new TypeError(`RS256 ${field} is not a PEM: expected "-----BEGIN ${expected}-----"`);
+  if (field === "privateKeyPem" && label === "RSA PRIVATE KEY") throw new TypeError("RS256 privateKeyPem is a PKCS#1 key (BEGIN RSA PRIVATE KEY); convert it to PKCS#8: openssl pkcs8 -topk8 -nocrypt -in key.pem -out key-pkcs8.pem");
+  if (field === "privateKeyPem" && label === "ENCRYPTED PRIVATE KEY") throw new TypeError("RS256 privateKeyPem is encrypted; remove the passphrase first: openssl pkcs8 -in key.pem -out key-plain.pem");
+  if (field === "privateKeyPem" && label.endsWith("PUBLIC KEY")) throw new TypeError("RS256 privateKeyPem contains a PUBLIC KEY; pass the private key (BEGIN PRIVATE KEY)");
+  if (field === "publicKeyPem" && label === "RSA PUBLIC KEY") throw new TypeError("RS256 publicKeyPem is a PKCS#1 public key (BEGIN RSA PUBLIC KEY); convert it to SPKI: openssl rsa -RSAPublicKey_in -in public.pem -pubout -out public-spki.pem");
+  if (field === "publicKeyPem" && label.endsWith("PRIVATE KEY")) throw new TypeError("RS256 publicKeyPem contains a private key; give verifiers only the public key: openssl pkey -in key.pem -pubout -out public.pem");
+  if (label !== expected || match === undefined || match === null) throw new TypeError(`RS256 ${field} is not a PEM: expected "-----BEGIN ${expected}-----"`);
+  if (!/^[A-Za-z0-9+/=\s]+$/.test(match[2]!)) throw new TypeError(`RS256 ${field} has an invalid base64 body`);
+  return pem;
+}
+
+/** Web Crypto says only "Invalid keyData"; name the key that failed. */
+async function importKey(which: "private" | "public", work: () => Promise<CryptoKey>): Promise<CryptoKey> {
+  try {
+    return await work();
+  } catch (error) {
+    throw new Error(`RS256 ${which} key could not be imported (${error instanceof Error ? error.message : String(error)}); check that it is an RSA ${which === "private" ? "PKCS#8 private" : "SPKI public"} key in PEM`, { cause: error });
+  }
+}
+
 /** Convenience factory for {@link Rs256Algorithm}. */
 export function rs256(keys: Rs256KeyMaterial): Rs256Algorithm {
   return new Rs256Algorithm(keys);

package/library/orm/Providers/PostgresProvider.ts

@@ -749,7 +749,7 @@ export class PostgresProvider implements DatabaseProvider {
         // Both query() and execute() can write in autocommit mode. Once handed
         // to the driver, a missing reply is not proof that replay is safe.
         if (autocommit && nativeQuery !== undefined && !isConfirmedStatementRejection(error)) {
-          const unknown = this.uncertainty(error);
+          const unknown = this.uncertainty(error, "statement");
           if (owner) {
             owner.unknownOutcome ??= unknown;
             owner.state = "quarantined";
@@ -1205,7 +1205,7 @@ export class PostgresProvider implements DatabaseProvider {
     } catch { return false; }
   }
 
-  private uncertainty(cause?: unknown, phase: "commit" | "cancellation" = "commit"): TransactionOutcomeUnknownError {
+  private uncertainty(cause?: unknown, phase: "commit" | "cancellation" | "statement" = "commit"): TransactionOutcomeUnknownError {
     const error = new TransactionOutcomeUnknownError(cause, phase); this.uncertainErrors.add(error); return error;
   }
 

package/library/orm/Providers/transactionOutcome.ts

@@ -5,13 +5,22 @@ import type { TransactionCallback } from "./types";
 export class TransactionOutcomeUnknownError extends DbUpdateError {
   readonly code = "ORM_TRANSACTION_OUTCOME_UNKNOWN";
   readonly outcome = "unknown";
-  constructor(override readonly cause?: unknown, readonly phase: "commit" | "cancellation" = "commit") {
+  /** `statement`: a statement sent outside a transaction got no answer (a timeout or a lost connection). */
+  constructor(override readonly cause?: unknown, readonly phase: "commit" | "cancellation" | "statement" = "commit") {
     super(phase === "commit"
       ? "Transaction outcome is unknown. Reconcile database state and use a new DbContext before saving again."
-      : "Transaction cancellation is unconfirmed. Reconcile database state and use a new DbContext before saving again.");
+      : phase === "statement"
+        ? `The database did not answer a statement sent outside a transaction${statementReason(cause)}. If the statement changed data, its outcome is unknown: check the data and use a new DbContext before saving again.`
+        : "Transaction cancellation is unconfirmed. Reconcile database state and use a new DbContext before saving again.");
   }
 }
 
+function statementReason(cause: unknown): string {
+  if (!(cause instanceof Error) || cause.message === "") return "";
+  const message = cause.message.replace(/\.$/, "");
+  return `: ${cause.name === "Error" || cause.name.startsWith("Orm") ? message : `${cause.name}: ${message}`}`;
+}
+
 export function isUnknownTransactionOutcome(error: unknown): boolean {
   const pending = [error];
   const seen = new Set<unknown>();

package/library/orm/Saving/SaveExecutor.ts

@@ -1,5 +1,5 @@
 import { Validator } from "../../validation";
-import { DbUpdateError, isCommittedOutcome, OrmValidationError, UniqueViolationError } from "../errors";
+import { DbUpdateError, isCommittedOutcome, OrmValidationError, translateDatabaseError } from "../errors";
 import { isDatabaseGenerated, type EntityModel } from "../Metadata/types";
 import { maxRowsPerInsert } from "../Providers/limits";
 import { decodeProperty } from "../Providers/propertyConversion";
@@ -170,7 +170,7 @@ export class SaveExecutor {
         // idempotent fallback also protects custom/top-level providers.
         this.restoreGeneratedKeys(generatedKeys);
         for (const token of tokens) this.restoreRollbackToken(token);
-        throw UniqueViolationError.from(error);
+        throw translateDatabaseError(error);
       }
       throw error;
     }

package/library/orm/Transactions/TransactionScopeCoordinator.ts

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { DbContext } from "../DbContext";
-import { ConcurrentTransactionScopeError, differentProviderMessage, OrmDatabaseTimeError, OrmProviderIdentityMismatchError, OrmTransactionScopeError } from "../errors";
+import { ConcurrentTransactionScopeError, differentProviderMessage, OrmDatabaseTimeError, OrmProviderIdentityMismatchError, OrmTransactionScopeError, translateDatabaseError } from "../errors";
 import { baseProvider, withPostgresScopeOptions, createObservedProvider, postgresTransactionCapability, rootAuthority, withProviderDispatchObserver, withoutProviderDispatchObserver, type CancellableProviderDispatch } from "../Providers/ormTransactionRuntime";
 import type { DatabaseProvider } from "../Providers/types";
 import { OrmTransaction, type OrmDatabaseTimeV1, type OrmTransactionScopeOptions } from "./OrmTransaction";
@@ -86,7 +86,9 @@ export function observedProvider(context: object, provider: DatabaseProvider): D
   const authority = rootAuthority(provider);
   const fence = <T>(operation: () => Promise<T>, view = views.getStore()): Promise<T> => {
     if (uncertainContexts.has(token)) return Promise.reject(new TransactionOutcomeUnknownError());
-    const guarded = () => operation().catch((error) => { if (postgresTransactionCapability(provider)?.isOutcomeUncertain?.(error)) uncertainContexts.add(token); throw error; });
+    // Known SQLSTATEs (unique, foreign key, check, not null, lock timeout)
+    // reach the context's caller as ORM errors; the outcome check sees the raw one.
+    const guarded = () => operation().catch((error) => { if (postgresTransactionCapability(provider)?.isOutcomeUncertain?.(error)) uncertainContexts.add(token); throw translateDatabaseError(error); });
     if (!view) return guarded();
     const frame = view.frame;
     if (frame.authority !== authority || !view.enrolled.has(token) || frame.state !== "active" || frame.activeChild !== undefined) {

package/library/orm/errors.ts

@@ -192,6 +192,89 @@ export class UniqueViolationError extends DbUpdateError {
   }
 }
 
+/** Reads a non-empty string field of a driver error. */
+function driverField(cause: object, name: string): string | undefined {
+  const value = (cause as Record<string, unknown>)[name];
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/** Copies the SQLSTATE so transaction-outcome checks see the same server rejection. */
+function copyServerCode(target: object, cause: object): void {
+  for (const name of ["errno", "code"]) {
+    const descriptor = Object.getOwnPropertyDescriptor(cause, name);
+    if (descriptor && "value" in descriptor) Object.defineProperty(target, name, { value: descriptor.value, enumerable: true });
+  }
+}
+
+/** A foreign key constraint was violated (SQLSTATE 23503). */
+export class ForeignKeyViolationError extends DbUpdateError {
+  readonly constraint: string | undefined;
+  readonly table: string | undefined;
+  constructor(cause: object) {
+    const constraint = driverField(cause, "constraint");
+    super(`Foreign key constraint${constraint === undefined ? "" : ` "${constraint}"`} violated: the row refers to a missing row, or a row that other rows refer to was deleted.`, { cause });
+    this.constraint = constraint;
+    this.table = driverField(cause, "table");
+    copyServerCode(this, cause);
+  }
+}
+
+/** A CHECK constraint was violated (SQLSTATE 23514). */
+export class CheckViolationError extends DbUpdateError {
+  readonly constraint: string | undefined;
+  readonly table: string | undefined;
+  constructor(cause: object) {
+    const constraint = driverField(cause, "constraint");
+    super(constraint === undefined ? "Check constraint violated." : `Check constraint "${constraint}" violated.`, { cause });
+    this.constraint = constraint;
+    this.table = driverField(cause, "table");
+    copyServerCode(this, cause);
+  }
+}
+
+/** A NOT NULL column got NULL (SQLSTATE 23502). */
+export class NotNullViolationError extends DbUpdateError {
+  readonly column: string | undefined;
+  readonly table: string | undefined;
+  constructor(cause: object) {
+    const column = driverField(cause, "column");
+    const table = driverField(cause, "table");
+    super(column === undefined ? "A NOT NULL column got NULL." : `Column "${column}"${table === undefined ? "" : ` of table "${table}"`} does not accept NULL.`, { cause });
+    this.column = column;
+    this.table = table;
+    copyServerCode(this, cause);
+  }
+}
+
+/** A lock was not granted within `lock_timeout` (SQLSTATE 55P03). */
+export class LockTimeoutError extends OrmError {
+  constructor(cause: object) {
+    super("A lock was not granted within lockTimeoutMs: another transaction holds the row or table. Retry the operation, or shorten the transaction that holds the lock.", { cause });
+    copyServerCode(this, cause);
+  }
+}
+
+const TRANSLATED: Readonly<Record<string, new (cause: object) => OrmError>> = {
+  "23505": UniqueViolationError,
+  "23503": ForeignKeyViolationError,
+  "23514": CheckViolationError,
+  "23502": NotNullViolationError,
+  "55P03": LockTimeoutError,
+};
+
+/**
+ * A driver error with a known SQLSTATE as its ORM error (unique, foreign key,
+ * check, not-null violation, lock timeout); anything else unchanged. The
+ * original error is `cause`; messages carry constraint and column names only,
+ * never row values.
+ */
+export function translateDatabaseError(error: unknown): unknown {
+  if (error === null || typeof error !== "object" || error instanceof OrmError) return error;
+  const errno = Object.getOwnPropertyDescriptor(error, "errno");
+  const Translated = errno && "value" in errno && typeof errno.value === "string" ? TRANSLATED[errno.value] : undefined;
+  return Translated === undefined ? error : new Translated(error);
+}
+
 /** The entity failed validation before saving. */
 export class OrmValidationError extends DbUpdateError {
   constructor(

package/library/orm/index.ts

@@ -151,6 +151,11 @@ export {
   OrmError,
   OrmValidationError,
   UniqueViolationError,
+  ForeignKeyViolationError,
+  CheckViolationError,
+  NotNullViolationError,
+  LockTimeoutError,
+  translateDatabaseError,
   PostCommitError,
   isCommittedOutcome,
   OrmTransactionScopeError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.98.24",
+  "version": "0.98.26",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",