@govcore/server 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# @govcore/server
+
+## 0.1.1
+
+### Patch Changes
+
+- f3bce48: `createTenantActions` now accepts a `createRbac()` instance for its `rbac` gate without a cast. `CreateTenantActionsConfig.rbac.hasPermission` is declared with method syntax so its bivariant parameters accept a gate typed with the app's role/permission _literals_ (what `@govcore/rbac` returns), while the active role is checked as a `string`. Removes a consumer footgun (#45).
+
+## 0.1.0
+
+### Minor Changes
+
+- 8db62da: Phase 4 (part 1) — the action seam and the accessibility floor.
+
+  `@govcore/server`: `createTenantActions` → a typed `tenantAction` wrapper. It
+  resolves the actor's active context (never trusting caller input), applies an
+  optional permission gate, opens a transaction and sets the transaction-local
+  `app.current_org` GUC so the schema's RLS policies bind to every query, and hands
+  the handler an `audit` fn pre-bound to the actor + org.
+
+  `@govcore/theme`: a WCAG-AA base token set (`base.css`, light/dark, visible focus
+  ring), a Tailwind `baseTheme` preset, and `defineTheme` — which only allows
+  overriding allowlisted brand vars and sanitizes values to prevent inline-`<style>`
+  breakout (#769).
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies [f2f3743]
+  - @govcore/audit@0.1.0
+  - @govcore/schema@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Allred
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+import { type GovcoreDb } from '@govcore/schema';
+import { type AuditEvent } from '@govcore/audit';
+/** The trusted, server-resolved identity of the current actor. */
+export interface ActiveContext {
+    userId: string;
+    organizationId: string;
+    role: string;
+    instanceRole?: string | null;
+}
+/** What a handler receives: the active context plus a pre-bound audit writer. */
+export interface TenantActionContext extends ActiveContext {
+    /** Write an audit row in the *same* transaction, pre-filled with actor + org. */
+    audit: (event: AuditEvent) => Promise<void>;
+}
+export interface CreateTenantActionsConfig {
+    db: GovcoreDb;
+    /** Resolve the current actor's active context — typically from the auth() session. */
+    getActiveContext: () => Promise<ActiveContext | null>;
+    /**
+     * Optional permission gate — pass an `@govcore/rbac` instance directly. Method
+     * syntax (not an arrow property) so its bivariant parameters accept a
+     * `createRbac<Role, Permission>()` whose `hasPermission` is typed with the
+     * app's role/permission *literals*, while the active role here is a `string`.
+     */
+    rbac?: {
+        hasPermission(role: string, permission: string): boolean;
+    };
+    /** Called when there is no active context. Default: throws Error('Unauthorized'). */
+    onUnauthorized?: () => never;
+    /** Called when the permission check fails. Default: throws Error('Forbidden'). */
+    onForbidden?: () => never;
+}
+export type TenantActionHandler<I, O> = (args: {
+    ctx: TenantActionContext;
+    db: GovcoreDb;
+}, input: I) => Promise<O>;
+export interface TenantActionOptions {
+    /** Permission required to run this action (checked against the active role). */
+    permission?: string;
+}
+/**
+ * Build the app's typed `tenantAction`. Call once at app startup with the app's
+ * db, session→context resolver, and rbac instance.
+ */
+export declare function createTenantActions(config: CreateTenantActionsConfig): <I = void, O = unknown>(options: TenantActionOptions, handler: TenantActionHandler<I, O>) => (input: I) => Promise<O>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAChD,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAE/D,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,cAAc,EAAE,MAAM,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAoB,SAAQ,aAAa;IACxD,iFAAiF;IACjF,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC5C;AAED,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,SAAS,CAAA;IACb,sFAAsF;IACtF,gBAAgB,EAAE,MAAM,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAA;IACrD;;;;;OAKG;IACH,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAA;IACnE,qFAAqF;IACrF,cAAc,CAAC,EAAE,MAAM,KAAK,CAAA;IAC5B,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,KAAK,CAAA;CAC1B;AAED,MAAM,MAAM,mBAAmB,CAAC,CAAC,EAAE,CAAC,IAAI,CACtC,IAAI,EAAE;IAAE,GAAG,EAAE,mBAAmB,CAAC;IAAC,EAAE,EAAE,SAAS,CAAA;CAAE,EACjD,KAAK,EAAE,CAAC,KACL,OAAO,CAAC,CAAC,CAAC,CAAA;AAEf,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,yBAAyB,IAGtC,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,OAAO,EAChD,SAAS,mBAAmB,EAC5B,SAAS,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,KACjC,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAiC5B"}

package/dist/index.js

@@ -0,0 +1,52 @@
+// @govcore/server — tenantAction, the enforced server-action seam.
+//
+// Every tenant-scoped mutation runs through here. tenantAction:
+//   1. resolves the actor's active context (never trusts caller input),
+//   2. applies a permission gate (if configured),
+//   3. opens a transaction and sets the transaction-local org GUC, so the RLS
+//      policies in @govcore/schema apply to every query in the handler, and
+//   4. hands the handler an audit fn pre-bound to the actor + org.
+//
+// The app builds its own typed `tenantAction` once via createTenantActions,
+// injecting its db, its session→context resolver, and its rbac instance.
+import { sql } from 'drizzle-orm';
+import { writeAuditLog } from '@govcore/audit';
+/**
+ * Build the app's typed `tenantAction`. Call once at app startup with the app's
+ * db, session→context resolver, and rbac instance.
+ */
+export function createTenantActions(config) {
+    const { db, getActiveContext, rbac } = config;
+    return function tenantAction(options, handler) {
+        return async (input) => {
+            const active = await getActiveContext();
+            if (!active) {
+                if (config.onUnauthorized)
+                    return config.onUnauthorized();
+                throw new Error('Unauthorized');
+            }
+            if (options.permission) {
+                const allowed = rbac?.hasPermission(active.role, options.permission) ?? false;
+                if (!allowed) {
+                    if (config.onForbidden)
+                        return config.onForbidden();
+                    throw new Error('Forbidden');
+                }
+            }
+            return db.transaction(async (tx) => {
+                // Transaction-local org GUC → RLS policies bind to every query below.
+                await tx.execute(sql `select set_config('app.current_org', ${active.organizationId}, true)`);
+                const txDb = tx;
+                const ctx = {
+                    ...active,
+                    audit: (event) => writeAuditLog(txDb, {
+                        ...event,
+                        userId: event.userId ?? active.userId,
+                        organizationId: event.organizationId ?? active.organizationId,
+                    }),
+                };
+                return handler({ ctx, db: txDb }, input);
+            });
+        };
+    };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@govcore/server",
+  "version": "0.1.1",
+  "description": "tenantAction — the server-action wrapper that opens the tenant transaction, sets the RLS org GUC, gates on permission, and binds audit",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "@govcore/audit": "0.1.0",
+    "@govcore/schema": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch"
+  }
+}

package/src/index.ts

@@ -0,0 +1,101 @@
+// @govcore/server — tenantAction, the enforced server-action seam.
+//
+// Every tenant-scoped mutation runs through here. tenantAction:
+//   1. resolves the actor's active context (never trusts caller input),
+//   2. applies a permission gate (if configured),
+//   3. opens a transaction and sets the transaction-local org GUC, so the RLS
+//      policies in @govcore/schema apply to every query in the handler, and
+//   4. hands the handler an audit fn pre-bound to the actor + org.
+//
+// The app builds its own typed `tenantAction` once via createTenantActions,
+// injecting its db, its session→context resolver, and its rbac instance.
+
+import { sql } from 'drizzle-orm'
+import { type GovcoreDb } from '@govcore/schema'
+import { writeAuditLog, type AuditEvent } from '@govcore/audit'
+
+/** The trusted, server-resolved identity of the current actor. */
+export interface ActiveContext {
+  userId: string
+  organizationId: string
+  role: string
+  instanceRole?: string | null
+}
+
+/** What a handler receives: the active context plus a pre-bound audit writer. */
+export interface TenantActionContext extends ActiveContext {
+  /** Write an audit row in the *same* transaction, pre-filled with actor + org. */
+  audit: (event: AuditEvent) => Promise<void>
+}
+
+export interface CreateTenantActionsConfig {
+  db: GovcoreDb
+  /** Resolve the current actor's active context — typically from the auth() session. */
+  getActiveContext: () => Promise<ActiveContext | null>
+  /**
+   * Optional permission gate — pass an `@govcore/rbac` instance directly. Method
+   * syntax (not an arrow property) so its bivariant parameters accept a
+   * `createRbac<Role, Permission>()` whose `hasPermission` is typed with the
+   * app's role/permission *literals*, while the active role here is a `string`.
+   */
+  rbac?: { hasPermission(role: string, permission: string): boolean }
+  /** Called when there is no active context. Default: throws Error('Unauthorized'). */
+  onUnauthorized?: () => never
+  /** Called when the permission check fails. Default: throws Error('Forbidden'). */
+  onForbidden?: () => never
+}
+
+export type TenantActionHandler<I, O> = (
+  args: { ctx: TenantActionContext; db: GovcoreDb },
+  input: I,
+) => Promise<O>
+
+export interface TenantActionOptions {
+  /** Permission required to run this action (checked against the active role). */
+  permission?: string
+}
+
+/**
+ * Build the app's typed `tenantAction`. Call once at app startup with the app's
+ * db, session→context resolver, and rbac instance.
+ */
+export function createTenantActions(config: CreateTenantActionsConfig) {
+  const { db, getActiveContext, rbac } = config
+
+  return function tenantAction<I = void, O = unknown>(
+    options: TenantActionOptions,
+    handler: TenantActionHandler<I, O>,
+  ): (input: I) => Promise<O> {
+    return async (input: I): Promise<O> => {
+      const active = await getActiveContext()
+      if (!active) {
+        if (config.onUnauthorized) return config.onUnauthorized()
+        throw new Error('Unauthorized')
+      }
+
+      if (options.permission) {
+        const allowed = rbac?.hasPermission(active.role, options.permission) ?? false
+        if (!allowed) {
+          if (config.onForbidden) return config.onForbidden()
+          throw new Error('Forbidden')
+        }
+      }
+
+      return db.transaction(async (tx) => {
+        // Transaction-local org GUC → RLS policies bind to every query below.
+        await tx.execute(sql`select set_config('app.current_org', ${active.organizationId}, true)`)
+        const txDb = tx as unknown as GovcoreDb
+        const ctx: TenantActionContext = {
+          ...active,
+          audit: (event) =>
+            writeAuditLog(txDb, {
+              ...event,
+              userId: event.userId ?? active.userId,
+              organizationId: event.organizationId ?? active.organizationId,
+            }),
+        }
+        return handler({ ctx, db: txDb }, input)
+      })
+    }
+  }
+}