@getstrata/core 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @getstrata/core changelog
 
+## 1.0.2
+
+- Lockstep with `create-strata` 1.0.2. No runtime changes.
+
+## 1.0.1
+
+- Publish the `contracts/authUserDirectory` subpath. Generated cookie and token apps import `AuthUserDirectory` from it, and without the export their `tsc --noEmit` failed with TS2307.
+- `SqlDialect` gains `timestampValue()`, plus a `sqlTimestamp()` helper. MySQL `DATETIME` rejects the ISO-8601 `T` separator and trailing `Z`, which broke cookie session inserts on MySQL.
+- `DatabaseConnection.close?()` now returns `void | Promise<void>`, matching the synchronous `close()` on the SQLite connection it is supposed to describe.
+- `engines.bun` is declared.
+- MySQL pools are UTC end to end: `createMysqlConnection()` passes `timezone: "Z"` to mysql2 and runs `SET time_zone = '+00:00'` on every new connection. Before, `DATETIME` values written as UTC by `timestampValue()` were read back shifted by the host offset, and `expires_at > NOW()` depended on the server time zone. `createMysqlPool(url)` exposes the configured raw pool.
+- SQLite `nowExpression()` is `strftime('%Y-%m-%dT%H:%M:%fZ', 'now')` instead of `CURRENT_TIMESTAMP`, matching the ISO-8601 text that `timestampValue()` writes. With `CURRENT_TIMESTAMP` the `T` separator sorted after the space, so an expired session compared as valid until the next UTC day.
+- Unknown exceptions map to `InternalServerError` (500, generic message) instead of a 400 that echoed the raw error text. SQLite (`SQLITE_CONSTRAINT_*`) and MySQL (`ER_DUP_ENTRY`, `ER_NO_REFERENCED_ROW_2`, `ER_ROW_IS_REFERENCED_2`, `ER_BAD_NULL_ERROR`, `ER_CHECK_CONSTRAINT_VIOLATED`) constraint errors map to 409/422/400 like Postgres SQLSTATEs. 5xx responses are logged with the original message and stack.
+- Client IP: `readClientIp()` falls back to the socket address the web server records in the request context, and with `TRUST_FORWARDED_FOR=true` takes the rightmost public `X-Forwarded-For` hop instead of the first (client-controlled) one. Throttles no longer collapse every client into an `unknown` bucket.
+- CORS: with `CORS_ALLOWED_ORIGINS` unset, production sends no `Access-Control-Allow-Origin` (same-origin only) instead of reflecting any origin; outside production the default stays `*`. Listed origins are reflected; unlisted ones get no header.
+- `TENANCY_DRIVER` must be `none`, `column`, or `rls`. Unknown values throw instead of enabling rls.
+- SQLite connections enable WAL, `busy_timeout = 5000`, and `synchronous = NORMAL` for file databases.
+- New subpath `runtime/appEnv` with `isProductionEnv()` (`APP_ENV` or `NODE_ENV`), used for the cookie `Secure` flag and for hiding 500 messages in HTML.
+
 ## 1.0.0
 
 - First stable release of the public `@getstrata/core` API.
@@ -19,7 +38,7 @@
 
 ## 0.7.2
 
-- `withJsonErrorHandling` always maps thrown errors to JSON. `requestPrefersJson` treats `/api/` as JSON even when `Accept` is HTML, so hybrid staff HTML cannot remap JSON API errors.
+- `withJsonErrorHandling` always maps thrown errors to JSON. `requestPrefersJson` treats `/api/` as JSON even when `Accept` is HTML, so hybrid HTML cannot remap JSON API errors.
 
 ## 0.7.1
 
@@ -28,20 +47,20 @@
 
 ## 0.7.0
 
-- `FRONTEND_MODE=hybrid` turns on staff HTML and the candidate SPA together. Views are on for `server-htmx` and `hybrid`. The SPA is on for `spa-react` and `hybrid`.
+- `FRONTEND_MODE=hybrid` turns on HTML at `/` and a SPA under `SPA_PREFIX` together. Views are on for `server-htmx` and `hybrid`. The SPA is on for `spa-react` and `hybrid`.
 - `parseFrontendMode`, `FRONTEND_MODES`, and `FRONTEND_MODE_PATTERN` are the allowed-value list. Apps should reuse that pattern in env schemas.
 - Named database connections: `registerNamedConnection`, `runOnNamedConnection`, SQLite (`bun:sqlite`), and MySQL (`mysql2`). `runWithSqlDialect` keeps the dialect across `await` via AsyncLocalStorage.
 - New subpaths: `database/namedConnections`, `database/sqliteConnection`, `database/mysqlConnection`, `database/connectionContext`.
-- OpenAPI treats `POST /api/apply/login` as unauthenticated.
+- OpenAPI treats unauthenticated login routes as public.
 
 ## 0.6.0
 
 - **Breaking:** cookie session signatures use HMAC-SHA256. Existing HMAC cookies signed with the previous digest will not verify. Rotate `SESSION_SECRET` or sign users in again.
-- **Breaking:** default `MEMBER_ABILITIES` are profile and token scopes (`profile:read`, `auth:tokens:*`), not org/project/task. Apps replace the catalog with `configureAbilityCatalog`. HiroApp maps admin / recruiter / candidate.
+- **Breaking:** default `MEMBER_ABILITIES` are profile and token scopes (`profile:read`, `auth:tokens:*`), not org/project/task. Apps replace the catalog with `configureAbilityCatalog`. Generated HiroApp maps admin / member.
 - Named auth guards: opaque Bearer tokens, JWT HS256, HTTP Basic, and cookie sessions. `AuthManager` picks a guard from the `Authorization` scheme. CSRF is skipped for Bearer and Basic.
-- OpenAPI treats HiroApp login, JWT mint (`POST /api/auth/token`), and public careers as unauthenticated. Partner ping and audit export require credentials.
+- OpenAPI treats HiroApp login and JWT mint (`POST /api/auth/token`) as unauthenticated. Partner ping and audit export require credentials.
 - SQL dialect helpers (`pgsql`, `mysql`, `sqlite`) for placeholders, quoting, `ILIKE`/`LIKE`, `RETURNING`, and `NULLS LAST`. Full-text `tsMatch` stays Postgres-only and throws on other engines.
-- HiroApp is the only in-repo example product. The leftover `src/db` schema is a test fixture, not a second app.
+- HiroApp is the in-repo generated example. The leftover `src/db` schema is a test fixture, not a second app.
 - New subpaths: `auth/jwt`, `auth/jwtGuard`, `auth/basicAuthGuard`, `auth/tokenAbilityChecker`, `database/dialect`, `http/statelessAuth`.
 
 ## 0.5.101
@@ -60,12 +79,12 @@ Still non-conforming (honest): Bun cannot infer `morphTo()` method names. `hashe
 
 ## 0.5.99
 
-HiroApp dogfood of 0.5.98 found lookalike APIs. This release matches the previous PHP framework call shape and SQL, not just export names.
+HiroApp dogfood of 0.5.98 found lookalike APIs. This release matches the existing call shape and SQL, not just export names.
 
 - Relation queries are thenable: `await user.applications()` delegates to `get()`.
 - `Model.with()` / `where()` / `whereHas()` return a `ModelQuery` that hydrates models and chains into `where` / `find` / `findOrFail` / `first` / `get`. `first()` / `find()` use `LIMIT` / PK lookup.
 - `belongsTo.where()` threads constraints into `whereHas` EXISTS (HiroApp application search).
-- `{ ilike }` uses the value as-is (the previous PHP framework). Pass `%term%` yourself; the operator no longer wraps extra `%`.
+- `{ ilike }` uses the value as-is. Pass `%term%` yourself; the operator no longer wraps extra `%`.
 - Morph type defaults to `$morphClass` / class name, not `table.name`. Override with `$morphClass = "App\\Models\\User"` or the last `morphMany` argument. `morphTo()` no longer silently defaults to `imageable_*`.
 - `primaryKey()` defaults to the table PK (`id`).
 - Nested `load("a.b")` / `with("a.b")` skip already-loaded heads and batch the next level.
@@ -80,13 +99,13 @@ Still non-conforming (honest): Bun cannot infer `morphTo()` method names (`debug
 
 ## 0.5.98
 
-- Eloquent-shaped relations: `this.hasMany(Related)` returns a relation query (`get`/`where`/`create`/`attach`). `load()` / `loaded()` and `Model.with()` replace PHP `__get`. `whereHas`/`has`/`doesntHave`, morph* methods, and nested `with("a.b")` are supported.
+- Model relations: `this.hasMany(Related)` returns a relation query (`get`/`where`/`create`/`attach`). `load()` / `loaded()` and `Model.with()` load related rows. `whereHas`/`has`/`doesntHave`, morph* methods, and nested `with("a.b")` are supported.
 - Model `$hidden`/`$visible`/`$appends`, `toArray()`/`toJSON()`, `makeHidden`/`makeVisible`/`append`, and `observe()`.
 - `Model.where()`, `firstOrNew()`, `firstOrCreate()`, and `updateOrCreate()`.
 - Factory `count`/`state`/`sequence`/`for`/`has`/`recycle` plus `afterMaking`/`afterCreating`.
 - `JsonResource` (`wrap`, `whenLoaded`, `additional`, `collection`).
-- the previous PHP framework aliases: container `make`/`instance`, EventBus `on`/`emit`, query `whereNull`/`whereIn`/`whereExists`.
-- Parity audit reports design score separately. Horizon/Nova/CLI stay Bun-native stand-ins.
+- Convenience aliases: container `make`/`instance`, EventBus `on`/`emit`, query `whereNull`/`whereIn`/`whereExists`.
+- Parity audit reports design score separately. Queue dashboards, admin UIs, and CLI stay Bun-native.
 
 ## 0.5.97
 
@@ -103,7 +122,7 @@ Still non-conforming (honest): Bun cannot infer `morphTo()` method names (`debug
 
 ## 0.5.90
 
-- **Breaking identity defaults:** `appKeyPrefix()` is `strata` and `appDisplayName()` is `Strata` when `APP_KEY_PREFIX` / `APP_NAME` are unset (were `strata` / `the previous in-repo app`). the previous in-repo app pins those env vars.
+- **Breaking identity defaults:** `appKeyPrefix()` is `strata` and `appDisplayName()` is `Strata` when `APP_KEY_PREFIX` / `APP_NAME` are unset (were `strata` / `HiroApp`). HiroApp pins those env vars.
 - `Schedule.command()` rejects cron strings other than `* * * * *` and `*/N * * * *` instead of silently never running them.
 - OpenAPI marks `GET /users/me/*` as bearer-authenticated.
 - OpenAPI `/users/me/current-organization` summaries no longer say team invitations.
@@ -115,11 +134,11 @@ Still non-conforming (honest): Bun cannot infer `morphTo()` method names (`debug
 ## 0.5.88
 
 - Exported cookie name constants (`SESSION_COOKIE`, `CSRF_COOKIE`, `FLASH_COOKIE`, `INTENDED_URL_COOKIE`, `PASSWORD_CONFIRM_COOKIE`) are `appCookieName(...)` so they match the default prefix instead of a hardcoded `strata_` string.
-- `@getstrata/core/jobs/dispatchWebhookJob` is a deprecated compatibility re-export of the the previous in-repo app webhook job.
+- `@getstrata/core/jobs/dispatchWebhookJob` is a deprecated compatibility re-export of the HiroApp webhook job.
 
 ## 0.5.87
 
-- `AuthUserDirectory.hasActiveBrowserSession?(userId, issuedAt)` is optional. `SessionGuard` calls it after `session_valid_after` and rejects the HMAC cookie when it returns false so the previous in-repo app can revoke a single browser session by deleting the `sessions` row.
+- `AuthUserDirectory.hasActiveBrowserSession?(userId, issuedAt)` is optional. `SessionGuard` calls it after `session_valid_after` and rejects the HMAC cookie when it returns false so HiroApp can revoke a single browser session by deleting the `sessions` row.
 
 ## 0.5.86
 
@@ -144,11 +163,11 @@ Still non-conforming (honest): Bun cannot infer `morphTo()` method names (`debug
 
 ## 0.5.81
 
-- `@getstrata/core/auth/intendedUrlCookie` (`createIntendedUrlCookie`, `readIntendedUrl`, `clearIntendedUrlCookie`, `createIntendedUrlCookieFromRequest`). HTML auth intended URL after HTML email verification: register with `redirect=` and the previous PHP framework `verified` HTML redirects stash `${APP_KEY_PREFIX}_intended` (`INTENDED_URL_COOKIE_NAME`, default `strata_intended`; TTL `INTENDED_URL_TTL_SECONDS`, default 86400s). `GET /verify-email` honors and clears it.
+- `@getstrata/core/auth/intendedUrlCookie` (`createIntendedUrlCookie`, `readIntendedUrl`, `clearIntendedUrlCookie`, `createIntendedUrlCookieFromRequest`). HTML auth intended URL after HTML email verification: register with `redirect=` and verified HTML redirects stash `${APP_KEY_PREFIX}_intended` (`INTENDED_URL_COOKIE_NAME`, default `strata_intended`; TTL `INTENDED_URL_TTL_SECONDS`, default 86400s). `GET /verify-email` honors and clears it.
 
 ## 0.5.80
 
-- `appCookieName()` / `appDevSecret()` on `@getstrata/core/runtime/appKeyPrefix`. HMAC session, CSRF, flash, password-confirm, signed-URL, OAuth-state, and token-pepper fallbacks follow `APP_KEY_PREFIX` (the previous in-repo app defaults unchanged).
+- `appCookieName()` / `appDevSecret()` on `@getstrata/core/runtime/appKeyPrefix`. HMAC session, CSRF, flash, password-confirm, signed-URL, OAuth-state, and token-pepper fallbacks follow `APP_KEY_PREFIX` (HiroApp defaults unchanged).
 
 ## 0.5.79
 
@@ -168,12 +187,12 @@ Still non-conforming (honest): Bun cannot infer `morphTo()` method names (`debug
 
 ## 0.5.75
 
-- the previous PHP framework `password.confirm`: `@getstrata/core/auth/passwordConfirmCookie` (`createPasswordConfirmCookie`, `hasFreshPasswordConfirmation`, `clearPasswordConfirmCookie`) and `createRequirePasswordConfirmMiddleware()` (HTML 302 `/confirm-password`, JSON 423). Cookie name `PASSWORD_CONFIRM_COOKIE_NAME` (default `strata_password_confirmed`), TTL `PASSWORD_CONFIRM_TIMEOUT` (default 10800s).
+- Password confirm: `@getstrata/core/auth/passwordConfirmCookie` (`createPasswordConfirmCookie`, `hasFreshPasswordConfirmation`, `clearPasswordConfirmCookie`) and `createRequirePasswordConfirmMiddleware()` (HTML 302 `/confirm-password`, JSON 423). Cookie name `PASSWORD_CONFIRM_COOKIE_NAME` (default `strata_password_confirmed`), TTL `PASSWORD_CONFIRM_TIMEOUT` (default 10800s).
 
 ## 0.5.74
 
 - `AuthUser.emailVerifiedAt` and `@getstrata/core/auth/emailVerification` (`isEmailVerificationRequired`, `hasVerifiedEmail`). `null` means unverified; missing is treated as verified (GuestGuard / legacy).
-- `createRequireVerifiedMiddleware()` is the previous PHP framework `verified` (HTML 302 `/email/verify`, JSON 403).
+- `createRequireVerifiedMiddleware()` requires a verified email (HTML 302 `/email/verify`, JSON 403).
 
 ## 0.5.73
 
@@ -198,40 +217,40 @@ Still non-conforming (honest): Bun cannot infer `morphTo()` method names (`debug
 
 ## 0.5.68
 
-- Published core no longer imports the previous in-repo app `src/config`. Frontend mode, queue retries, CORS, and upload limits read env (`FRONTEND_MODE`, `QUEUE_*`, `CORS_ALLOWED_ORIGINS`, `MAX_UPLOAD_BYTES`).
+- Published core no longer imports HiroApp `src/config`. Frontend mode, queue retries, CORS, and upload limits read env (`FRONTEND_MODE`, `QUEUE_*`, `CORS_ALLOWED_ORIGINS`, `MAX_UPLOAD_BYTES`).
 - `@getstrata/core/runtime/frontendMode` exports `readFrontendMode` / `isViewsEnabled` / `isSpaEnabled`.
 
 ## 0.5.67
 
-- OpenAPI title, server URLs, and generated SDK class name come from `APP_NAME` / `APP_URL` / `API_PREFIX` / `APP_SDK_CLASS` instead of importing the previous in-repo app `src/config/app`.
-- `appEnv()`, `appUrl()`, `apiPrefix()`, and `sdkClientClassName()` live on `@getstrata/core/runtime/appKeyPrefix`. SIEM export, HSTS, and `safeFetch` DNS resolve use `appEnv()` instead of the previous in-repo app `appConfig`.
+- OpenAPI title, server URLs, and generated SDK class name come from `APP_NAME` / `APP_URL` / `API_PREFIX` / `APP_SDK_CLASS` instead of importing HiroApp `src/config/app`.
+- `appEnv()`, `appUrl()`, `apiPrefix()`, and `sdkClientClassName()` live on `@getstrata/core/runtime/appKeyPrefix`. SIEM export, HSTS, and `safeFetch` DNS resolve use `appEnv()` instead of HiroApp `appConfig`.
 
 ## 0.5.66
 
-- `createValidateSignatureMiddleware()` on `@getstrata/core/http/signedUrl` is the previous PHP framework's `signed` / `ValidateSignature` middleware. Invalid or expired links throw `ForbiddenError`.
+- `createValidateSignatureMiddleware()` on `@getstrata/core/http/signedUrl` rejects invalid or expired signed links with `ForbiddenError`.
 
 ## 0.5.65
 
-- Identity helpers on `@getstrata/core/runtime/appKeyPrefix` (`smtpEhloHost`, `siemEventType`, `appUserAgent`, `otelServiceName`, `appDisplayName`, `webhookSignatureHeader`) so sibling apps are not stuck with the previous in-repo app SMTP/SIEM/OTEL/OAuth names.
-- SIEM `event_type` and CEF vendor follow `SIEM_EVENT_TYPE` / `APP_NAME` (defaults stay `strata.audit` / `the previous in-repo app`).
+- Identity helpers on `@getstrata/core/runtime/appKeyPrefix` (`smtpEhloHost`, `siemEventType`, `appUserAgent`, `otelServiceName`, `appDisplayName`, `webhookSignatureHeader`) so sibling apps are not stuck with HiroApp SMTP/SIEM/OTEL/OAuth names.
+- SIEM `event_type` and CEF vendor follow `SIEM_EVENT_TYPE` / `APP_NAME` (defaults stay `strata.audit` / `HiroApp`).
 
 ## 0.5.64
 
-- `APP_KEY_PREFIX` (default `strata`) namespaces Redis cache, queue, and throttle keys so sibling apps do not share the previous in-repo app's keyspace.
-- `DispatchWebhookJob` implementation lives in the the previous in-repo app webhook module. `@getstrata/core/jobs/dispatchWebhookJob` remains a compatibility re-export.
+- `APP_KEY_PREFIX` (default `strata`) namespaces Redis cache, queue, and throttle keys so sibling apps do not share HiroApp's keyspace.
+- `DispatchWebhookJob` implementation lives in the HiroApp webhook module. `@getstrata/core/jobs/dispatchWebhookJob` remains a compatibility re-export.
 
 ## 0.5.63
 
-- Flash cookies honor `FLASH_COOKIE_NAME` (default `strata_flash`) so sibling apps do not inherit the previous in-repo app's cookie name.
+- Flash cookies honor `FLASH_COOKIE_NAME` (default `strata_flash`) so sibling apps do not inherit HiroApp's cookie name.
 
 ## 0.5.62
 
-the previous PHP framework URL signing, Bun-native markdown mail, and session-auth cleanup.
+URL signing, Bun-native markdown mail, and session-auth cleanup.
 
 - `temporarySignedUrl` / `signedUrl` / `hasValidSignature` / `assertValidSignature` on `@getstrata/core/http/signedUrl`. HMAC uses `SIGNED_URL_SECRET` or `SESSION_SECRET`. Paths must be same-origin (`/` only; reject `//` and `://`).
 - `markdownToHtml()` uses `Bun.markdown.html()` plus `sanitizeMailHtml` (allowlist). Scripts, `javascript:` links, and unknown tags are stripped.
 - `ExportAuditLogsJob` (`@getstrata/core/jobs/exportAuditLogsJob`) wraps SIEM export so the scheduler can dispatch a real job.
-- `DispatchWebhookJob` reads `APP_ENV` and `WEBHOOK_SIGNATURE_HEADER` instead of the previous in-repo app `appConfig`.
+- `DispatchWebhookJob` reads `APP_ENV` and `WEBHOOK_SIGNATURE_HEADER` instead of HiroApp `appConfig`.
 - `createRequireWebAuthMiddleware` runs the handler inside `runWithAuthUser` so `currentAuthUser()` works on HTMX session routes.
 - `generateTotpSecret()` / `buildOtpauthUrl()` on `@getstrata/core/security/totp`.
 - `createRequireAbilityMiddleware` rethrows `ForbiddenError` for HTML views so HTMX routes render a styled 403 instead of JSON.
@@ -255,13 +274,13 @@ HTMX HTML kernel gaps that sibling apps could not work around without weakening
 
 ## 0.5.59
 
-Sibling HTMX apps can consume published packages without the previous in-repo app-only glue.
+Sibling HTMX apps can consume published packages without HiroApp-only glue.
 
 - Emit `@getstrata/core/facades` types at `dist/core/facades/index.d.ts` (CI checks every `exports.*.types` path after build).
-- Session and CSRF cookie names are configurable (`SESSION_COOKIE_NAME`, `CSRF_COOKIE_NAME`). Defaults remain `strata_session` and `strata_csrf` for the previous in-repo app.
+- Session and CSRF cookie names are configurable (`SESSION_COOKIE_NAME`, `CSRF_COOKIE_NAME`). Defaults remain `strata_session` and `strata_csrf` for HiroApp.
 - Split `CORE_ABILITY_CHECKER_TOKEN` and `CORE_AUTH_USER_DIRECTORY_TOKEN` from `CORE_TOKEN_SERVICE_TOKEN`. HttpKernel prefers the ability-checker token; HMAC `SessionGuard` / layout data prefer the user directory. A compatibility shim uses `CORE_TOKEN_SERVICE_TOKEN` only when the bound value matches the requested type.
-- `configureWebLayoutData` lets apps choose `currentUser` vs `authUser`, a custom user loader, and extra template fields. the previous in-repo app still gets `{ authUser, csrfToken, flash }`.
+- `configureWebLayoutData` lets apps choose `currentUser` vs `authUser`, a custom user loader, and extra template fields. HiroApp still gets `{ authUser, csrfToken, flash }`.
 - `redirectResponse`, `notFoundHtmlResponse`, `textResponse`, and `xmlResponse` join `htmlResponse` / `isHtmxRequest` on `@getstrata/core/view`.
 - `LOGIN_RATE_LIMIT_WINDOW_MS` is a deprecated alias for `LOGIN_RATE_LIMIT_WINDOW_SECONDS`.
 
-HMAC `SessionGuard` is unchanged for the previous in-repo app API/token apps. Sibling HTMX apps should use `@getstrata/bootstrap` `CookieSessionStore` + `createCookieSessionAuthManager`.
+HMAC `SessionGuard` is unchanged for HiroApp API/token apps. Sibling HTMX apps should use `@getstrata/bootstrap` `CookieSessionStore` + `createCookieSessionAuthManager`.

package/README.md

@@ -1,71 +1,64 @@
 # @getstrata/core
 
-Stable **Strata** framework surface for application modules.
+Runtime library for [Strata](https://github.com/EyK-26/strata) apps: HTTP, auth, database, queue, mail, and security. Requires Bun (tested on 1.4.x).
 
-**Source:** `src/framework/public-api.ts` (monorepo)
-**Repository:** [EyK-26/strata](https://github.com/EyK-26/strata), directory `packages/strata-core`
+Generate an app rather than wiring this by hand:
 
-HiroApp is the example product. Import this package from your own modules. HTML cookie apps: [docs/BUILDING-APPS.md](../../docs/BUILDING-APPS.md). Auth choices: [docs/AUTH.md](../../docs/AUTH.md). SQL engines: [docs/DATABASE.md](../../docs/DATABASE.md).
+```bash
+bunx create-strata my-app
+```
 
-## Usage
+## Import subpaths, not the root
 
-Set `DATABASE_URL` before importing (the connection is created lazily on first query):
+Apps, and anything they import, should use subpaths:
 
 ```typescript
-process.env.DATABASE_URL ??= "postgresql://postgres:postgres@localhost:5432/myapp";
-
-import { Policy } from "@getstrata/core/auth/policy";
+import { createAuthMiddleware } from "@getstrata/core/http/authMiddleware";
+import { bindDatabaseConnection } from "@getstrata/core/database/bindConnection";
 import { BaseRepository } from "@getstrata/core/database/baseRepository";
 import { FormRequest } from "@getstrata/core/http/formRequest";
+import { Policy } from "@getstrata/core/auth/policy";
 import { withErrorHandling } from "@getstrata/core/http/response";
-import { EtaViewEngine } from "@getstrata/core/view";
+import { ValidationError } from "@getstrata/core/errors/http";
+import type { Migration } from "@getstrata/core/database/migrations/types";
 ```
 
-`.eta` files are **HTML + Eta tags** (`<% %>`, `<%= %>`, `<%~ include() %>`), not another template language. Class/attribute shorthand such as `section.section` or `a href=` fails at render time with the template name.
-
-**Dependency:** `eta` is a direct dependency of `@getstrata/core`. Apps do not need to list it separately. The database **engine** is your choice. Generated HiroApp uses **Bun's built-in `Bun.sql`** (Postgres): `createBunSqlPool()`, then `registerDefaultDatabasePool()` and `bindDatabaseConnection()`. `bindBunSql()` is a helper that registers both. Extra engines register with `registerNamedConnection` (`database/namedConnections`, `database/sqliteConnection`, `database/mysqlConnection`).
-
-`orderBy` accepts `{ column, direction }` objects or column shorthand such as `{ published_at: "desc" }`. `{ ilike }` uses the value as-is. Pass `%term%` yourself.
+The root `@getstrata/core` import resolves, but nothing stops you from ending up with two copies of process-wide state: the database pool, the dialect override, async-local auth and tenant context, and the `HttpError` base class used with `instanceof`. Some subpaths re-export the main bundle for exactly that reason. Prefer subpaths everywhere and the problem does not arise.
 
-## Admin and queue helpers
+## Database
 
-- `AdminResourceRegistry`, `formatAdminValue`: read-only resource browsers
-- `createFailedJobService`, `FailedJobService.delete()`: failed job persistence and cleanup
-- `runQueueJob`, `jobRegistry`: dispatch retried jobs from admin UIs
+Set `DATABASE_URL` before the first query; the connection is created lazily.
 
-Core ships failed-job helpers and an optional admin resource registry. Generated HiroApp does not include an admin dashboard. You do not have to use the registry.
+```typescript
+process.env.DATABASE_URL ??= "postgresql://postgres:postgres@localhost:5432/myapp";
+```
 
-## Build and verify (monorepo root)
+The engine is your choice, and an app should have one primary engine. Postgres apps use Bun's built-in `Bun.sql` through `createBunSqlPool()`, then `registerDefaultDatabasePool()` and `bindDatabaseConnection()`; `bindBunSql()` registers both. SQLite and MySQL register through `database/sqliteConnection` and `database/mysqlConnection`, or `registerNamedConnection` from `database/namedConnections`.
 
-```bash
-bun run build:framework
-bun run verify:framework
-bun run verify:shared-subpaths
-```
+`orderBy` takes `{ column, direction }` objects or column shorthand such as `{ published_at: "desc" }`. `{ ilike }` uses the value as-is, so pass `%term%` yourself.
 
-## Subpath imports
+Full-text `tsMatch` is PostgreSQL only.
 
-`@getstrata/core` publishes many subpaths (for example `@getstrata/core/http/authMiddleware`, `@getstrata/core/database/migrations`). Prefer subpaths over the root import in apps, bootstrap, and tests.
+`mysql2` and `eta` are direct dependencies, so they install even for a SQLite JSON API app.
 
-Some subpaths **re-export the main bundle** so singleton state stays shared (database pool, dialect override, async-local auth/tenant, `HttpError` for `instanceof`). The list lives in `scripts/core-shared-subpaths.ts`.
+## Views
 
-When adding a subpath that owns process-wide state or base classes used with `instanceof`, append it to `CORE_SHARED_SUBPATHS`, run `bun scripts/sync-package-subpaths.ts`, and rebuild.
+`.eta` files are HTML plus Eta tags (`<% %>`, `<%= %>`, `<%~ include() %>`). Pug-style class or id shorthand such as `section.section` throws at render time and names the offending template.
 
-`scripts/verify-no-root-imports.ts` blocks root `@getstrata/core` imports in application source.
+## Admin and queue helpers
 
-```typescript
-import { createAuthMiddleware } from "@getstrata/core/http/authMiddleware";
-import { bindDatabaseConnection } from "@getstrata/core/database/bindConnection";
-import { ValidationError } from "@getstrata/core/errors/http";
-import type { Migration } from "@getstrata/core/database/migrations/types";
-```
+- `AdminResourceRegistry`, `formatAdminValue`: read-only resource browsers
+- `createFailedJobService`, `FailedJobService.delete()`: failed job persistence and cleanup
+- `runQueueJob`, `jobRegistry`: dispatch retried jobs from admin UIs
 
-## Publish to npm
+Generated apps do not include an admin dashboard, and the registry is optional.
 
-Package name: **`@getstrata/core`** (npm org [`@getstrata`](https://www.npmjs.com/org/getstrata)).
+## Docs
 
-1. Add `NPM_TOKEN` to GitHub repository secrets.
-2. Tag a release: `git tag v1.0.0 && git push origin v1.0.0`
-3. [Release workflow](../../.github/workflows/release.yml) builds and runs `npm publish --access public`.
+- [Getting started](https://github.com/EyK-26/strata/blob/main/docs/GETTING-STARTED.md)
+- [Building apps](https://github.com/EyK-26/strata/blob/main/docs/BUILDING-APPS.md)
+- [Auth choices](https://github.com/EyK-26/strata/blob/main/docs/AUTH.md)
+- [Databases](https://github.com/EyK-26/strata/blob/main/docs/DATABASE.md)
+- [Production](https://github.com/EyK-26/strata/blob/main/docs/PRODUCTION.md)
 
-See [docs/PACKAGING.md](../../docs/PACKAGING.md).
+Contributing to the framework itself: [CONTRIBUTING.md](https://github.com/EyK-26/strata/blob/main/CONTRIBUTING.md).

package/dist/core/database/baseRepository.d.ts

@@ -10,7 +10,8 @@ type ExtendedQueryOptions<TEntity extends object> = QueryOptions<TEntity> & {
 interface DatabaseConnection {
     unsafe<T>(query: string, params?: readonly unknown[]): Promise<T[]>;
     begin?<T>(callback: (transaction: DatabaseConnection) => Promise<T>): Promise<T>;
-    close?(): Promise<void>;
+    /** SQLite closes synchronously; pooled drivers return a promise. */
+    close?(): void | Promise<void>;
 }
 interface SqlDatabaseConnection extends DatabaseConnection {
     (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>;

package/dist/core/database/dialect.d.ts

@@ -4,6 +4,8 @@ interface SqlDialect {
     placeholder(index: number): string;
     quoteIdentifier(identifier: string): string;
     nowExpression(): string;
+    /** Render a Date as a literal this engine accepts for a timestamp column. */
+    timestampValue(value: Date): string;
     returningClause(columns: string): string;
     ilikeOperator(): "ILIKE" | "LIKE";
     nullsLastSuffix(): string;
@@ -12,7 +14,9 @@ interface SqlDialect {
 declare function dialectFor(driver: DatabaseDriver): SqlDialect;
 declare function currentSqlDialect(): SqlDialect;
 declare function useSqlDialect(driver: DatabaseDriver): SqlDialect;
+/** Format a timestamp parameter for whichever engine is active. */
+declare function sqlTimestamp(value?: Date): string;
 declare function resetSqlDialect(): void;
 declare function runWithSqlDialect<T>(driver: DatabaseDriver, callback: () => T | Promise<T>): T | Promise<T>;
 export type { SqlDialect };
-export { currentSqlDialect, dialectFor, resetSqlDialect, runWithSqlDialect, useSqlDialect };
+export { currentSqlDialect, dialectFor, resetSqlDialect, runWithSqlDialect, sqlTimestamp, useSqlDialect, };

package/dist/core/database/errors.d.ts

@@ -7,6 +7,10 @@ interface PostgresErrorLike {
     message?: string;
 }
 declare function isPostgresError(error: unknown): error is PostgresErrorLike;
+/**
+ * Constraint violations become 4xx with a fixed message. Anything else is a
+ * 500 with a generic message; the raw driver text never reaches the client.
+ */
 declare function mapDatabaseError(error: unknown): HttpError;
 declare function withDatabaseErrorHandling<TValue>(operation: () => Promise<TValue>): Promise<TValue>;
 export { isPostgresError, mapDatabaseError, withDatabaseErrorHandling };

package/dist/core/database/mysqlConnection.d.ts

@@ -1,3 +1,4 @@
+import mysql from "mysql2/promise";
 import type { ActiveDatabaseHandle } from "./connectionContext.ts";
 type MysqlExecutable = {
     execute: (sql: string, params?: unknown[]) => Promise<[unknown, unknown]>;
@@ -7,6 +8,7 @@ type MysqlConnection = ActiveDatabaseHandle & {
     close(): Promise<void>;
 };
 declare function createMysqlConnectionFromPool(pool: MysqlExecutable): MysqlConnection;
+declare function createMysqlPool(url: string): mysql.Pool;
 declare function createMysqlConnection(url: string): MysqlConnection;
 export type { MysqlConnection, MysqlExecutable };
-export { createMysqlConnection, createMysqlConnectionFromPool };
+export { createMysqlConnection, createMysqlConnectionFromPool, createMysqlPool };

package/dist/core/errors/http.d.ts

@@ -30,6 +30,9 @@ declare class PayloadTooLargeError extends HttpError {
 declare class PreconditionFailedError extends HttpError {
     constructor(message?: string, details?: unknown);
 }
+declare class InternalServerError extends HttpError {
+    constructor(message?: string, details?: unknown);
+}
 interface HttpErrorLike {
     status: number;
     message: string;
@@ -37,4 +40,4 @@ interface HttpErrorLike {
 }
 declare function isHttpErrorLike(error: unknown): error is HttpErrorLike;
 declare function toHttpError(error: unknown): HttpError | null;
-export { BadRequestError, ConflictError, ForbiddenError, HttpError, isHttpErrorLike, NotFoundError, PayloadTooLargeError, PreconditionFailedError, toHttpError, UnauthorizedError, UnprocessableEntityError, ValidationError, };
+export { BadRequestError, ConflictError, ForbiddenError, HttpError, InternalServerError, isHttpErrorLike, NotFoundError, PayloadTooLargeError, PreconditionFailedError, toHttpError, UnauthorizedError, UnprocessableEntityError, ValidationError, };

package/dist/core/http/clientIp.d.ts

@@ -1,3 +1,6 @@
-declare function trustForwardedFor(env?: Record<string, string | undefined>): boolean;
-declare function readClientIp(request: Request, env?: Record<string, string | undefined>): string | undefined;
-export { readClientIp, trustForwardedFor };
+type EnvRecord = Record<string, string | undefined>;
+declare function trustForwardedFor(env?: EnvRecord): boolean;
+declare function isPrivateAddress(address: string): boolean;
+/** Forwarded headers only when trusted; otherwise the socket address the server recorded. */
+declare function readClientIp(request: Request, env?: EnvRecord): string | undefined;
+export { isPrivateAddress, readClientIp, trustForwardedFor };

package/dist/core/http/webErrorResponse.d.ts

@@ -1,5 +1,7 @@
+import { type HttpError } from "@getstrata/core/errors/http";
 type FieldErrors = Record<string, string[]>;
 declare function normalizeFieldErrors(details: unknown): FieldErrors;
+declare function logServerError(error: unknown, mappedError: HttpError): void;
 declare function webErrorResponse(error: unknown, request?: Request): Promise<Response | null>;
 export type { FieldErrors };
-export { normalizeFieldErrors, webErrorResponse };
+export { logServerError, normalizeFieldErrors, webErrorResponse };

package/dist/core/runtime/appEnv.d.ts

@@ -0,0 +1,4 @@
+type EnvRecord = Record<string, string | undefined>;
+/** Production when either the framework or the Node convention says so. */
+declare function isProductionEnv(env?: EnvRecord): boolean;
+export { isProductionEnv };

package/dist/core/tenant/tenancyConfig.d.ts

@@ -1,4 +1,5 @@
 type TenancyDriver = "rls" | "column" | "none";
+/** Unset means rls (the Postgres example). Anything else must be an exact driver name. */
 declare function readTenancyDriver(env?: Record<string, string | undefined>): TenancyDriver;
 declare function isTenancyEnabled(env?: Record<string, string | undefined>): boolean;
 /** Postgres `SET LOCAL` / `set_config` for row-level security. SQLite and MySQL cannot do this. */

package/dist/entries/audit/exportAuditLogs.js

@@ -191,14 +191,16 @@ async function safeFetch(input, init = {}, options = {}) {
 import { repositoryConnection as db } from "@getstrata/core/database/repositoryConnection";
 
 // ../../src/core/tenant/tenancyConfig.ts
+var TENANCY_DRIVERS = ["rls", "column", "none"];
 function readTenancyDriver(env = process.env) {
-  if (env.TENANCY_DRIVER === "none") {
-    return "none";
+  const raw = env.TENANCY_DRIVER?.trim();
+  if (raw === undefined || raw === "") {
+    return "rls";
   }
-  if (env.TENANCY_DRIVER === "column") {
-    return "column";
+  if (TENANCY_DRIVERS.includes(raw)) {
+    return raw;
   }
-  return "rls";
+  throw new Error(`TENANCY_DRIVER must be one of ${TENANCY_DRIVERS.join(", ")}; received "${raw}".`);
 }
 function isTenancyEnabled(env = process.env) {
   return readTenancyDriver(env) !== "none";

package/dist/entries/auth/scimAuthMiddleware.js

@@ -78,14 +78,16 @@ function resolveScimTenantFromToken(token) {
 import { repositoryConnection as db } from "@getstrata/core/database/repositoryConnection";
 
 // ../../src/core/tenant/tenancyConfig.ts
+var TENANCY_DRIVERS = ["rls", "column", "none"];
 function readTenancyDriver(env = process.env) {
-  if (env.TENANCY_DRIVER === "none") {
-    return "none";
+  const raw = env.TENANCY_DRIVER?.trim();
+  if (raw === undefined || raw === "") {
+    return "rls";
   }
-  if (env.TENANCY_DRIVER === "column") {
-    return "column";
+  if (TENANCY_DRIVERS.includes(raw)) {
+    return raw;
   }
-  return "rls";
+  throw new Error(`TENANCY_DRIVER must be one of ${TENANCY_DRIVERS.join(", ")}; received "${raw}".`);
 }
 function isTenancyEnabled(env = process.env) {
   return readTenancyDriver(env) !== "none";

package/dist/entries/contracts/authUserDirectory.js

@@ -0,0 +1 @@
+// @bun

package/dist/entries/database/errors.js

@@ -3,6 +3,7 @@
 import {
   BadRequestError,
   ConflictError,
+  InternalServerError,
   toHttpError,
   UnprocessableEntityError
 } from "@getstrata/core/errors/http";
@@ -21,14 +22,55 @@ function getPostgresSqlState(error) {
   }
   return;
 }
+var MYSQL_ERRNO_MESSAGES = {
+  1062: () => new ConflictError("A record with these values already exists."),
+  1451: () => new UnprocessableEntityError("Record is still referenced by other records."),
+  1452: () => new UnprocessableEntityError("Referenced record does not exist."),
+  1048: () => new BadRequestError("Required field is missing."),
+  3819: () => new BadRequestError("Value violates a database constraint.")
+};
+function mapSqliteError(error) {
+  const code = typeof error.code === "string" ? error.code : "";
+  if (!code.startsWith("SQLITE_")) {
+    return null;
+  }
+  if (code === "SQLITE_CONSTRAINT_UNIQUE" || code === "SQLITE_CONSTRAINT_PRIMARYKEY") {
+    return new ConflictError("A record with these values already exists.");
+  }
+  if (code === "SQLITE_CONSTRAINT_FOREIGNKEY") {
+    return new UnprocessableEntityError("Referenced record does not exist.");
+  }
+  if (code === "SQLITE_CONSTRAINT_NOTNULL") {
+    return new BadRequestError("Required field is missing.");
+  }
+  if (code.startsWith("SQLITE_CONSTRAINT")) {
+    return new BadRequestError("Value violates a database constraint.");
+  }
+  return new InternalServerError("Database operation failed.");
+}
+function mapMysqlError(error) {
+  const code = typeof error.code === "string" ? error.code : "";
+  if (!code.startsWith("ER_")) {
+    return null;
+  }
+  const factory = typeof error.errno === "number" ? MYSQL_ERRNO_MESSAGES[error.errno] : undefined;
+  return factory ? factory() : new InternalServerError("Database operation failed.");
+}
 function mapDatabaseError(error) {
   const httpError = toHttpError(error);
   if (httpError) {
     return httpError;
   }
   if (!isPostgresError(error)) {
-    const message = error instanceof Error ? error.message : "Database operation failed.";
-    return new BadRequestError(message);
+    return new InternalServerError;
+  }
+  const sqlite = mapSqliteError(error);
+  if (sqlite) {
+    return sqlite;
+  }
+  const mysql = mapMysqlError(error);
+  if (mysql) {
+    return mysql;
   }
   const sqlState = getPostgresSqlState(error);
   switch (sqlState) {
@@ -49,10 +91,7 @@ function mapDatabaseError(error) {
         constraint: error.constraint
       });
     default:
-      return new BadRequestError(error.message ?? "Database operation failed.", {
-        code: error.code,
-        sqlState
-      });
+      return new InternalServerError("Database operation failed.");
   }
 }
 async function withDatabaseErrorHandling(operation) {

package/dist/entries/database/mysqlConnection.js

@@ -23,13 +23,29 @@ function createMysqlConnectionFromPool(pool) {
     }
   };
 }
+var MYSQL_SESSION_UTC = "SET time_zone = '+00:00'";
+function pinSessionToUtc(connection) {
+  connection.query(MYSQL_SESSION_UTC, (error) => {
+    if (error) {
+      console.warn(`[mysql] Could not set the session time zone to UTC; DATETIME comparisons may drift: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  });
+}
+function createMysqlPool(url) {
+  const pool = mysql.createPool({ uri: url, timezone: "Z" });
+  pool.on("connection", (connection) => {
+    pinSessionToUtc(connection);
+  });
+  return pool;
+}
 function createMysqlConnection(url) {
   if (!url.trim()) {
     throw new Error("MYSQL_URL is not configured. Set url before creating a MySQL pool.");
   }
-  return createMysqlConnectionFromPool(mysql.createPool(url));
+  return createMysqlConnectionFromPool(createMysqlPool(url));
 }
 export {
   createMysqlConnection,
-  createMysqlConnectionFromPool
+  createMysqlConnectionFromPool,
+  createMysqlPool
 };

package/dist/entries/database/sqliteConnection.js

@@ -14,6 +14,11 @@ function createSqliteConnection(filename) {
   }
   const db = new Database(filename, { create: true });
   db.exec("PRAGMA foreign_keys = ON");
+  db.exec("PRAGMA busy_timeout = 5000");
+  if (filename !== ":memory:") {
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec("PRAGMA synchronous = NORMAL");
+  }
   return {
     async unsafe(query, params = []) {
       const statement = db.query(query);