@exvio/os-backend-core 0.4.0

package/README.md

@@ -0,0 +1,466 @@
+# @exvio/os-backend-core
+
+Shared backend building blocks for the Wellous OS hub-and-spoke fleet.
+
+This package plays the same governance role for backend infrastructure that
+`@exvio/os-theme` plays for frontend UI: one implementation, versioned releases,
+and deliberate upgrades in each consumer. It ships TypeScript source because
+every current consumer runs on Bun and already type-checks with bundler module
+resolution.
+
+## Scope law
+
+The package owns infrastructure that has the same contract in multiple Wellous
+backends. It must not own a product's routes, role model, database schema,
+migrations, environment names, tenant table catalogue, or domain services.
+
+Dependency direction is one-way:
+
+```text
+consumer backend  --->  @exvio/os-backend-core
+        adapters  --->  db / redis / logger / config supplied by the app
+```
+
+Core modules never import a consumer repository. Infrastructure that needs an
+application service must be exposed as a factory and receive a narrow adapter.
+
+## v0.1 tenant API
+
+The first release owns the shared `AsyncLocalStorage` tenant context and the
+Kysely AST plugin that scopes tenant-aware queries.
+
+```ts
+import {
+  TenantFilterPlugin,
+  bypassTenant,
+  tenantContext,
+  withTenant,
+} from '@exvio/os-backend-core/tenant'
+
+const db = new Kysely<Database>({
+  dialect,
+  plugins: [
+    new TenantFilterPlugin(TENANT_AWARE_TABLES, {
+      context: tenantContext,
+      // Transitional v0.1 policy. Move to `throw` after every non-HTTP entry
+      // point has an explicit tenant or bypass scope.
+      onMissingContext: 'passthrough',
+    }),
+    // Query profiler goes after the tenant filter so it sees executed SQL.
+  ],
+})
+
+await tenantContext.run({ tenantId: requestTenantId, bypass: false }, handleRequest)
+await withTenant(jobTenantId, runBackgroundJob)
+await bypassTenant(runReviewedCrossTenantOperation)
+```
+
+The consumer remains the source of truth for `TENANT_AWARE_TABLES`. The plugin
+only receives that `ReadonlySet<string>`; it does not know any product schema.
+The constructor snapshots the set so later mutation cannot alter the boundary.
+Entries are case-sensitive bare table names. A tenant-scoped table migration or
+rename must update the consumer catalogue and its sentinel test in the same PR.
+
+### Security contract
+
+- HTTP tenant middleware must wrap the entire downstream request in
+  `tenantContext.run(...)`.
+- WebSockets, background jobs, cron, queues, workers, and fire-and-forget tasks
+  must use `withTenant(...)` for each tenant; HTTP context is not a substitute
+  for an explicit non-HTTP entry boundary. `withTenant` accepts only positive
+  safe-integer tenant ids.
+- `bypassTenant(...)` is only for reviewed cross-tenant operations.
+- No context currently preserves the fleet's existing behaviour: the plugin
+  passes the query through by default. Consumers must explicitly configure the
+  transitional policy, audit every entry point, and then switch to
+  `onMissingContext: 'throw'`.
+- Raw `sql\`...\`` fragments are opaque to Kysely's AST transformer and must
+  include their own tenant predicate.
+- Joined tenant tables are currently supported for INNER and LEFT joins
+  (including their lateral forms). RIGHT, FULL, CROSS, USING-join, and APPLY
+  variants fail loudly when the joined side is tenant-aware because placing a
+  predicate in `ON` would not safely filter their preserved side.
+- `DELETE ... USING` tenant tables are scoped in the outer `WHERE`.
+- A tenant-scoped `UPDATE` cannot assign `tenant_id`. Multi-table targets and
+  dynamic/raw update-column names fail loudly because the package cannot prove
+  their ownership semantics. Ownership changes require a separately reviewed
+  cross-tenant operation.
+- `INSERT ... SELECT` and `INSERT ... DEFAULT VALUES` against a tenant-aware
+  table fail loudly. The only escape is a narrowly scoped `bypassTenant(...)`
+  operation that explicitly guarantees the projected tenant id.
+- UPSERT and REPLACE variants fail loudly for tenant-aware targets. Until a
+  conflict key can be proven to include `tenant_id`, they can otherwise match
+  and mutate another tenant's row through a globally unique key.
+- With an active tenant context, `MERGE` currently fails loudly for every table
+  because the Kysely AST cannot yet be rewritten safely.
+- Compile and execute a query inside the intended context; do not compile it in
+  one scope and execute it in another.
+
+All context users and `TenantFilterPlugin` must resolve the same installed
+package instance. Do not mix a copied tenant context with the packaged plugin.
+The optional `context` constructor argument makes this dependency explicit and
+protects linked development/HMR from using a different singleton instance.
+
+`tenantContext` is exposed for compatibility with HTTP middleware. Application
+code must not call its `enterWith()` or `disable()` methods; prefer
+`withTenant()`, `bypassTenant()`, and `getCurrentTenant()`.
+
+Migration and seed commands must make their policy explicit. During the v0.1
+transition they may rely on `passthrough`; before enabling strict mode, move
+them to a dedicated Kysely instance without the tenant plugin or wrap each
+reviewed operation in the appropriate scope.
+
+## v0.2 AI runtime (alpha)
+
+The AI subpath centralizes provider transport and runtime behaviour without
+owning a product's prompts, tools, tier rules, RAG, workflows, config tables, or
+usage ledger.
+
+```ts
+import { createAIClient } from '@exvio/os-backend-core/ai'
+import { createDeepSeekProvider } from '@exvio/os-backend-core/ai/providers/deepseek'
+import { createGeminiProvider } from '@exvio/os-backend-core/ai/providers/gemini'
+import { getCurrentTenant } from '@exvio/os-backend-core/tenant'
+
+const ai = createAIClient({
+  providers: new Map([
+    ['gemini', createGeminiProvider()],
+    ['deepseek', createDeepSeekProvider()],
+  ]),
+  // The app still owns DB/Redis config and must keep this tenant-isolated.
+  configSource: {
+    loadConfig: tenantId => loadAIConfig(tenantId, { fallback: false }),
+  },
+  tenantResolver: () => {
+    const context = getCurrentTenant()
+    return context && !context.bypass ? context.tenantId : undefined
+  },
+  missingTenantPolicy: 'throw',
+  telemetry: observeRedactedInvocation,
+})
+
+const result = await ai.generateText('Rewrite this clearly.', {
+  tenantId,
+  lane: 'text',
+  metadata: { feature: 'editor.rephrase' },
+})
+
+// A reliable product ledger must use the returned result, not telemetry.
+await recordUsage({
+  tenantId,
+  provider: result.provider,
+  model: result.model,
+  usage: result.usage,
+})
+```
+
+The application config adapter returns explicit provider/model pairs:
+
+```ts
+{
+  providers: {
+    gemini: { apiKey: '...' },
+    deepseek: {
+      apiKey: '...',
+      endpoint: 'https://api.deepseek.com/chat/completions',
+    },
+  },
+  lanes: {
+    text: { provider: 'gemini', model: 'gemini-2.5-flash' },
+    vision: { provider: 'gemini', model: 'gemini-2.5-flash' },
+    chat: { provider: 'deepseek', model: 'deepseek-v4-flash' },
+    embedding: { provider: 'gemini', model: 'gemini-embedding-001' },
+  },
+}
+```
+
+There is no model-prefix inference or silent provider fallback in the new API.
+`parseAIConfig()` also applies Core's built-in model lifecycle policy to every
+named lane, including custom lanes and explicit `{ provider, model }` entries.
+Retired identifiers fail at config load; only an explicit forward data
+migration may use `replacementForRetiredAIModelId()` to rewrite stored config.
+Credentials are loaded per invocation and provider instances are not shared
+between tenants. Missing tenant context fails by default. The built-in tenant
+resolver intentionally ignores a `bypassTenant(...)` scope; a reviewed
+cross-tenant operation must pass a positive `tenantId` on every AI call. A
+positive explicit tenant must match a normal active tenant context; callers
+cannot use an option to escape request tenancy. Enter a reviewed bypass scope
+before making an intentional cross-tenant call. A
+custom endpoint must be HTTPS, contain no URL credentials, and pass the
+application's `validateEndpoint` policy before an Authorization header is
+created. A provider factory's immutable official endpoint is the only endpoint
+accepted without that hook. The built-in Gemini adapter additionally accepts
+only Google's official API origin.
+
+`AIClientOptions.fetch` is an injectable transport for HTTP providers such as
+DeepSeek. The production Gemini adapter uses the official `@google/genai` SDK,
+which cannot honor that injected transport; it fails loudly if the client is
+configured with a custom `fetch` instead of silently bypassing the application's
+transport policy.
+
+Every text, content, chat, structured-output, stream, and embedding result uses
+the same actual-model and token-usage envelope. A stream may retry only before
+its first emitted event. Tool arguments and structured JSON fail closed rather
+than becoming `{}`. Telemetry is scalar, secret-free, non-blocking, and
+best-effort: a sink failure never changes a successful AI result, and telemetry
+must not be used as a reliable billing or usage ledger. Persist non-stream usage
+from the returned `AIResult`; for streaming, persist the `result` carried by the
+terminal `finish` event.
+
+### Adding providers and lanes
+
+The registry and lane names are open strings, so adding OpenAI, Anthropic,
+Azure AI, an on-prem model, or a future vendor does not require changing the
+consumer API. Implement an `AIProviderFactory`, declare its capabilities, add
+provider conformance tests, register it in each application's config adapter,
+and add an explicit `{ provider, model }` selection. Product call sites remain
+on `generateText`, `generateContent`, `generateChat`, `streamChat`,
+`generateObject`, or `embed`.
+
+Multiple providers and lanes can be active for the same tenant at the same
+time. For example, `text` may use DeepSeek, `vision` Gemini, `chat` a private
+provider, and `embedding` a dedicated embedding model. New product-specific
+lanes such as `workflow`, `classification`, or `assessment` require only a new
+config entry; Core does not maintain a closed lane enum. Automatic fallback,
+load balancing, or cost routing must be an explicit application policy and may
+never silently change the reported provider/model.
+
+Model/lane selection and prices are deliberately application-owned; rates are
+not bundled. Use `createPriceCatalog()` with an operations-owned
+version/effective date and `calculateCostUsd()`. Unknown models return `null`,
+not a misleading zero-dollar value. Product prompts, personas, RAG/vector-store
+policy, tool execution/authorization, and workflows also remain outside core.
+
+## v0.3 Changelog runtime (alpha)
+
+The Changelog subpath centralizes immutable release-note catalogues, weighted
+language negotiation, and per-subject acknowledgement state without owning an
+application's content, HTTP routes, user table, or migrations.
+
+```ts
+import {
+  createChangelogCatalogue,
+  createChangelogService,
+} from '@exvio/os-backend-core/changelog'
+
+const catalogue = createChangelogCatalogue({
+  entries: appReleaseNotes, // newest first; versions are opaque keys
+  locales: ['en', 'cn', 'bm'] as const,
+  defaultLocale: 'en',
+  languageTags: { zh: 'cn', ms: 'bm' },
+  maxVersionLength: 64, // must match the consumer database column
+})
+
+const changelog = createChangelogService({
+  catalogue,
+  acknowledgements: appAcknowledgementStore,
+})
+
+const state = await changelog.getState({
+  subjectId: authenticatedUserId,
+  acceptLanguage: request.headers.get('Accept-Language'),
+})
+```
+
+The first array entry is the latest release. Core never sorts versions by
+SemVer, text, or display date. Every acknowledgement must name an exact known
+version, so a late acknowledgement for an older screen may make a newer release
+reappear but can never silently hide it. The catalogue snapshots and freezes
+consumer input, requires the default-locale body, and allows older entries to
+fall back when an optional translation is absent.
+
+The acknowledgement store always receives both `tenantId` and `subjectId`.
+The default resolver reads the package tenant context, ignores bypass scopes,
+and fails when no tenant exists. An explicit tenant is allowed for reviewed
+background or bypass work, but it may not disagree with an active non-bypass
+tenant. Consumer repositories should use the supplied subject as their scope;
+they must not query by user id alone.
+
+Hono status codes, request-body limits, authentication, Kysely queries,
+database migrations, release-note Markdown, and frontend sanitization remain
+application-owned. HTTP adapters should project only the documented response
+fields and send personalized responses with `Cache-Control: no-store, private`.
+
+## v0.3 Guide runtime (alpha)
+
+The Guide subpath owns the common file-content mechanics used by every backend:
+manifest validation, deterministic grouping, locale fallback, bounded Markdown
+reads, frontmatter parsing, visibility policies, and removal of private
+`ai-context` authoring comments.
+
+```ts
+import path from 'node:path'
+import {
+  createFileGuideContentSource,
+  createGuideService,
+} from '@exvio/os-backend-core/guide'
+
+const guides = createGuideService({
+  locales: ['en', 'cn'] as const,
+  defaultLocale: 'en',
+  categories: appGuideCategories,
+  entries: appGuideEntries,
+  source: createFileGuideContentSource({
+    root: path.resolve('src/data/guides'),
+    maxFileBytes: 512_000,
+  }),
+  // These are separate by design: hiding an item in a catalogue is not
+  // automatically authorization for its detail route.
+  listPolicy: (entry, context) => includeGuideInCatalogue(entry, context),
+  readPolicy: (entry, context) => mayReadGuide(entry, context),
+})
+
+await guides.validate() // CI/startup asset audit
+const document = await guides.load({ category, slug, locale, context })
+```
+
+Category, slug, and locale identifiers are validated before file access. The
+file source requires an explicit absolute root, resolves real paths, rejects
+resolved symlink escapes, and caps reads. The root must be a Git/deployment-owned
+read-only asset directory; this adapter is not a sandbox for a directory that
+an untrusted process can rename or rewrite concurrently. Manifest input is deeply snapshotted and
+case-insensitive filesystem collisions fail at construction. Locale fallback
+returns both the requested and actual resolved locale.
+
+Frontmatter intentionally supports only `title` and `description`, handles BOM,
+LF, and CRLF, and rejects duplicate or unknown fields. User-facing bodies always
+remove `<!-- ai-context ... -->`; an unclosed marker removes the rest of the
+document rather than leaking private authoring material. The first API does not
+offer a raw or bulk AI loader.
+
+Applications retain their Markdown, manifest metadata, role model, Hono/i18n
+adapter, MCP and AI prompt adapters, and any tenant-specific overrides. Core
+policies receive the app's generic context but do not know `UserRole`. Routes
+must explicitly project response fields instead of serializing the returned
+extensible manifest entry. Markdown-to-HTML rendering and DOM sanitization are
+a frontend/theme responsibility.
+
+## v0.4 Auth runtime (alpha)
+
+The first Auth slice centralizes framework-neutral login policy, atomic OAuth
+transactions, non-bearer session-management handles, lifetime calculation, and
+secret redaction. It does not own users, roles, Hono routes, Redis, Kysely,
+provider credentials, or product authorization.
+
+```ts
+import {
+  createLoginPolicy,
+  createOAuthBrowserExchangeManager,
+  createOAuthStateManager,
+  createSessionBearerToken,
+  createSessionManagementHandle,
+} from '@exvio/os-backend-core/auth'
+
+const policy = createLoginPolicy({
+  mode: tenantIsHubManaged ? 'hub_managed' : 'standalone',
+  enabled: { email: true, google: true, microsoft: false, passkey: true },
+})
+policy.assertAllowed({ surface: 'google', phase: 'start' })
+
+const oneTimeStore = {
+  put: (key, value, ttlSeconds) => redis.set(key, value, ttlSeconds),
+  // This must be one Redis GETDEL command or one Lua script.
+  take: key => redis.getdel(key),
+}
+const oauthState = createOAuthStateManager({ store: oneTimeStore })
+const browserExchange = createOAuthBrowserExchangeManager({ store: oneTimeStore })
+
+const state = await oauthState.issue({
+  tenantId,
+  provider: 'google',
+  redirectUri,
+  verifier: pkceVerifier,
+  initiatingSessionId: browserTransactionCookie,
+})
+
+const exchangeCode = await browserExchange.issue({
+  tenantId,
+  browserTransaction: browserTransactionCookie,
+  provider: 'google',
+  userId,
+  // Optional revocation epoch captured before provider authentication.
+  sessionGeneration,
+})
+```
+
+The OAuth manager generates the state token and stores only its SHA-256-derived
+key. Consumption binds the exact tenant, provider, redirect URI, and optional
+initiating session, then burns the record before returning the PKCE verifier.
+Missing, malformed, expired, replayed, tenant-swapped, provider-swapped, and
+redirect-swapped transactions fail with a secret-free `AuthError`.
+
+After a successful provider callback, the browser exchange manager creates a
+short-lived, one-time code bound to the tenant, browser transaction, provider,
+user, optional session revocation generation, and expiry. It stores only a SHA-256-derived key and atomically burns the
+record before comparing the tenant and browser binding, so mismatch, replay,
+and concurrent consumption fail closed. The application owns the Secure,
+HttpOnly, SameSite=Lax transaction cookie, Hono exchange endpoint, final login
+policy/user checks, and session creation. A callback redirects with only the
+exchange code; a bearer token, PKCE verifier, OAuth state, and user projection
+must never be placed in the URL.
+
+### Passkey alpha boundary
+
+The Auth alpha also provides framework-neutral Passkey challenge transactions,
+distributed rate-limit decisions, recent-auth evaluation, HMAC-derived WebAuthn
+user handles, and signature-counter compare-and-swap rules. Registration binds
+the positive tenant and user ids, initiating session, recent authentication
+time, RP ID, origin, and excluded credentials. Authentication binds the
+positive tenant id, optional user, RP ID, origin, and allowed credential set.
+Both flows consume stored state atomically before comparison; missing, replayed,
+concurrent, malformed, purpose-swapped, or context-swapped finishes fail with a
+secret-free `PasskeyAuthError`.
+
+Core supplies no Redis or SQL client. A challenge adapter must implement atomic
+`take` with Redis `GETDEL` (or one equivalent Lua command), and authentication
+issuance also requires atomic `putIfAbsent`. The application supplies the Redis
+Lua rate-limit adapter and tenant-aware SQL counter CAS, plus Hono routes,
+SimpleWebAuthn verification, RP configuration, trusted-proxy address policy,
+credential persistence, recent-auth UX, security notifications, and durable
+audit storage. Durable Passkey audit is not implemented by this alpha and is a
+release blocker wherever policy or compliance requires it.
+
+`createSessionManagementHandle()` derives a stable `smh_v1_...` handle for a
+session-management screen. That handle cannot authenticate a request. A
+consumer must still verify the authenticated owner before revocation and must
+never return or log the underlying bearer. New sessions use the disjoint
+`sat_v1_...` namespace from `createSessionBearerToken()`; raw random values,
+`smh_v1_...` handles, and `oas_v1_...` states are not session bearers. Consumers
+enforce both idle and absolute expiry with `remainingSessionTtl()` and revoke
+the request's previous session after every successful authentication or
+privilege-changing rotation.
+
+The mode and surface matrix is shared, but role hierarchies are not. Each
+product's action permissions, object access, workflow ownership, entitlements
+and API-key/MCP scope catalogues remain application policy.
+
+`redactAuthSecrets()` and `redactAuthStorageKey()` produce log-safe values. The
+storage-key redactor bundles only generic auth namespaces (`session:`,
+`oauth:state:`, `passkey:auth:`, `password:reset:` and similar); an
+application's own credential-bearing key prefixes are passed on each call, for
+example `redactAuthStorageKey(key, ['ticket:', 'invite:'])`. A key that matches
+no prefix is returned unchanged, so an unlisted namespace is a logging leak, not
+a redaction.
+
+## Install
+
+The package is on the public npm registry under the `@exvio` scope. No git, ssh
+or AWS credentials are needed on the consumer side, and a Docker build that runs
+`bun install` needs nothing beyond registry access: no Git, no SSH client, no key
+to forward.
+
+```powershell
+bun add @exvio/os-backend-core
+```
+
+```json
+{ "dependencies": { "@exvio/os-backend-core": "^0.4.0" } }
+```
+
+Pin exactly (`0.4.0`, no caret) where a consumer must not pick up a minor: on a
+0.x line every minor may carry a breaking change.
+
+Published versions are immutable and every consumer upgrades explicitly. A
+pre-release version (`0.5.0-alpha.1`) is published under the `next` dist-tag and
+never moves `latest`. Contributor workflow, gates and the release procedure are
+in the source repository's `CONTRIBUTING.md`, which is not part of the package.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@exvio/os-backend-core",
+  "version": "0.4.0",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "type": "module",
+  "description": "Shared backend building blocks for the Wellous OS hub-and-spoke fleet.",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./tenant": "./src/tenant.ts",
+    "./auth": "./src/auth/index.ts",
+    "./changelog": "./src/changelog/index.ts",
+    "./guide": "./src/guide/index.ts",
+    "./ai": "./src/ai/index.ts",
+    "./ai/providers/gemini": "./src/ai/providers/gemini.ts",
+    "./ai/providers/deepseek": "./src/ai/providers/deepseek.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "type-check": "bun x tsc -p tsconfig.json --noEmit",
+    "test": "bun test",
+    "assert:publish-safe": "node scripts/assert-publish-safe.mjs",
+    "check": "bun run type-check && bun test"
+  },
+  "engines": {
+    "bun": ">=1.3.10"
+  },
+  "peerDependencies": {
+    "kysely": ">=0.28.16 <0.29.0"
+  },
+  "dependencies": {
+    "@google/genai": "2.17.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "kysely": "^0.28.17",
+    "typescript": "^5.9.3"
+  }
+}