@constructive-io/express-context 0.2.0

package/loaders/rls.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * RLS Module Loader
+ *
+ * Resolves RLS authentication function names and schema references for
+ * a given database. Tries the new rls_settings table first, falls back
+ * to the legacy api_modules approach.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rlsLoader = void 0;
+const create_loader_1 = require("./create-loader");
+// ─── SQL ────────────────────────────────────────────────────────────────────
+const RLS_SETTINGS_SQL = `
+  SELECT
+    auth_schema.schema_name AS authenticate_schema,
+    role_schema.schema_name AS role_schema,
+    auth_fn.name AS authenticate,
+    auth_strict_fn.name AS authenticate_strict,
+    role_fn.name AS current_role,
+    role_id_fn.name AS current_role_id,
+    ua_fn.name AS current_user_agent,
+    ip_fn.name AS current_ip_address
+  FROM services_public.rls_settings rs
+  LEFT JOIN metaschema_public.schema auth_schema ON rs.authenticate_schema_id = auth_schema.id
+  LEFT JOIN metaschema_public.schema role_schema ON rs.role_schema_id = role_schema.id
+  LEFT JOIN metaschema_public.function auth_fn ON rs.authenticate_function_id = auth_fn.id
+  LEFT JOIN metaschema_public.function auth_strict_fn ON rs.authenticate_strict_function_id = auth_strict_fn.id
+  LEFT JOIN metaschema_public.function role_fn ON rs.current_role_function_id = role_fn.id
+  LEFT JOIN metaschema_public.function role_id_fn ON rs.current_role_id_function_id = role_id_fn.id
+  LEFT JOIN metaschema_public.function ua_fn ON rs.current_user_agent_function_id = ua_fn.id
+  LEFT JOIN metaschema_public.function ip_fn ON rs.current_ip_address_function_id = ip_fn.id
+  WHERE rs.database_id = $1
+  LIMIT 1
+`;
+const RLS_MODULE_SQL = `
+  SELECT data
+  FROM services_public.api_modules
+  WHERE api_id = $1 AND name = 'rls_module'
+  LIMIT 1
+`;
+// ─── Transforms ─────────────────────────────────────────────────────────────
+function fromSettings(row) {
+    if (!row)
+        return undefined;
+    if (!row.authenticate || !row.authenticate_schema)
+        return undefined;
+    return {
+        authenticate: row.authenticate,
+        authenticateStrict: row.authenticate_strict,
+        privateSchema: { schemaName: row.authenticate_schema },
+        publicSchema: { schemaName: row.role_schema },
+        currentRole: row.current_role,
+        currentRoleId: row.current_role_id,
+        currentIpAddress: row.current_ip_address,
+        currentUserAgent: row.current_user_agent,
+    };
+}
+function fromModule(row) {
+    if (!row?.data)
+        return undefined;
+    const d = row.data;
+    return {
+        authenticate: d.authenticate,
+        authenticateStrict: d.authenticate_strict,
+        privateSchema: { schemaName: d.authenticate_schema },
+        publicSchema: { schemaName: d.role_schema },
+        currentRole: d.current_role,
+        currentRoleId: d.current_role_id,
+        currentIpAddress: d.current_ip_address,
+        currentUserAgent: d.current_user_agent,
+    };
+}
+// ─── Loader ─────────────────────────────────────────────────────────────────
+exports.rlsLoader = (0, create_loader_1.createModuleLoader)({
+    name: 'rlsModule',
+    ttlMs: 5 * 60_000,
+    async resolve(ctx) {
+        const { servicesPool, databaseId, apiId } = ctx;
+        // Try new rls_settings table first
+        try {
+            const result = await servicesPool.query(RLS_SETTINGS_SQL, [databaseId]);
+            const resolved = fromSettings(result.rows[0] ?? null);
+            if (resolved)
+                return resolved;
+        }
+        catch {
+            // Table may not exist yet
+        }
+        // Fall back to legacy api_modules
+        if (apiId) {
+            const result = await servicesPool.query(RLS_MODULE_SQL, [apiId]);
+            return fromModule(result.rows[0] ?? null);
+        }
+        return undefined;
+    },
+});

package/loaders/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Module Loader Types
+ *
+ * A ModuleLoader is a per-database cached lookup that resolves config
+ * from the services DB or tenant DB. Each loader owns its own LRU cache
+ * keyed by databaseId, with independent TTL and eviction.
+ *
+ * Loaders are registered in a LoaderRegistry and resolved in parallel
+ * during context building. The result is a typed modules map on
+ * `req.constructive.modules`.
+ */
+import type { Pool } from 'pg';
+/**
+ * Context passed to every loader's resolve function.
+ * Provides both pool references so the loader can query whichever
+ * database tier it needs.
+ */
+export interface LoaderContext {
+    /** Services database pool (for services_public.* lookups) */
+    servicesPool: Pool;
+    /** Tenant database pool (for metaschema_modules_public.* lookups) */
+    tenantPool: Pool;
+    /** UUID of the database being resolved */
+    databaseId: string;
+    /** UUID of the API (if resolved from domain/api-name lookup) */
+    apiId?: string;
+    /** Tenant database name */
+    dbname: string;
+}
+/**
+ * A single module loader. Encapsulates the SQL query, type transform,
+ * and per-databaseId LRU cache for one piece of per-database config.
+ */
+export interface ModuleLoader<T = unknown> {
+    /** Unique name (used in log prefix and as the key in the modules map) */
+    readonly name: string;
+    /** Resolve the module config for a given database. Returns undefined if not provisioned. */
+    resolve(ctx: LoaderContext): Promise<T | undefined>;
+    /** Invalidate the cache for one database (or all databases if omitted) */
+    invalidate(databaseId?: string): void;
+    /** Current number of cached entries */
+    readonly cacheSize: number;
+}

package/loaders/types.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Module Loader Types
+ *
+ * A ModuleLoader is a per-database cached lookup that resolves config
+ * from the services DB or tenant DB. Each loader owns its own LRU cache
+ * keyed by databaseId, with independent TTL and eviction.
+ *
+ * Loaders are registered in a LoaderRegistry and resolved in parallel
+ * during context building. The result is a typed modules map on
+ * `req.constructive.modules`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/loaders/webauthn.d.ts

@@ -0,0 +1,9 @@
+/**
+ * WebAuthn Settings Loader
+ *
+ * Resolves WebAuthn/passkey configuration for a database — RP identity,
+ * schema references, attestation policy, and challenge expiry.
+ */
+import type { WebauthnSettings } from '../types';
+import type { ModuleLoader } from './types';
+export declare const webauthnLoader: ModuleLoader<WebauthnSettings>;

package/loaders/webauthn.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * WebAuthn Settings Loader
+ *
+ * Resolves WebAuthn/passkey configuration for a database — RP identity,
+ * schema references, attestation policy, and challenge expiry.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.webauthnLoader = void 0;
+const create_loader_1 = require("./create-loader");
+// ─── SQL ────────────────────────────────────────────────────────────────────
+const WEBAUTHN_SETTINGS_SQL = `
+  SELECT
+    s.schema_name AS schema,
+    cred_s.schema_name AS credentials_schema,
+    sess_s.schema_name AS sessions_schema,
+    sec_s.schema_name AS session_secrets_schema,
+    ws.rp_id,
+    ws.rp_name,
+    ws.origin_allowlist,
+    ws.attestation_type,
+    ws.require_user_verification,
+    ws.resident_key,
+    ws.challenge_expiry_seconds
+  FROM services_public.webauthn_settings ws
+  LEFT JOIN metaschema_public.schema s ON ws.schema_id = s.id
+  LEFT JOIN metaschema_public.schema cred_s ON ws.credentials_schema_id = cred_s.id
+  LEFT JOIN metaschema_public.schema sess_s ON ws.sessions_schema_id = sess_s.id
+  LEFT JOIN metaschema_public.schema sec_s ON ws.session_secrets_schema_id = sec_s.id
+  WHERE ws.database_id = $1
+  LIMIT 1
+`;
+// ─── Loader ─────────────────────────────────────────────────────────────────
+exports.webauthnLoader = (0, create_loader_1.createModuleLoader)({
+    name: 'webauthnSettings',
+    ttlMs: 5 * 60_000,
+    async resolve(ctx) {
+        const { servicesPool, databaseId } = ctx;
+        const result = await servicesPool.query(WEBAUTHN_SETTINGS_SQL, [databaseId]);
+        const row = result.rows[0];
+        if (!row?.schema)
+            return undefined;
+        return {
+            schema: row.schema,
+            credentialsSchema: row.credentials_schema,
+            sessionsSchema: row.sessions_schema,
+            sessionSecretsSchema: row.session_secrets_schema,
+            rpId: row.rp_id,
+            rpName: row.rp_name,
+            originAllowlist: row.origin_allowlist,
+            attestationType: row.attestation_type,
+            requireUserVerification: row.require_user_verification,
+            residentKey: row.resident_key,
+            challengeExpirySeconds: row.challenge_expiry_seconds,
+        };
+    },
+});

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@constructive-io/express-context",
+  "version": "0.2.0",
+  "description": "Extractable Express middleware for Constructive tenant context — domain resolution, JWT auth, pgSettings, and withPgClient",
+  "author": "Constructive <developers@constructive.io>",
+  "homepage": "https://github.com/constructive-io/constructive",
+  "license": "MIT",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest --passWithNoTests",
+    "test:watch": "jest --watch"
+  },
+  "dependencies": {
+    "@constructive-io/url-domains": "^2.16.0",
+    "@pgpmjs/env": "^2.24.0",
+    "@pgpmjs/logger": "^2.11.0",
+    "@pgpmjs/server-utils": "^3.12.0",
+    "@pgpmjs/types": "^2.28.0",
+    "lru-cache": "^11.2.7",
+    "pg": "^8.21.0",
+    "pg-cache": "^3.11.0",
+    "pg-query-context": "^2.16.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/pg": "^8.20.0",
+    "express": "^5.2.1",
+    "makage": "^0.3.0"
+  },
+  "peerDependencies": {
+    "express": "^5.0.0"
+  },
+  "keywords": [
+    "constructive",
+    "express",
+    "middleware",
+    "context",
+    "tenant",
+    "domain",
+    "auth",
+    "jwt",
+    "pgSettings"
+  ],
+  "gitHead": "c0d04574f7719d92e67becb58d60791ae978c5f5"
+}

package/pg-client.d.ts

@@ -0,0 +1,8 @@
+/**
+ * pg-client — Re-exports withPgClient from pg-query-context
+ *
+ * This module exists for backwards compatibility. The implementation
+ * lives in pg-query-context which provides both the single-query API
+ * and the callback-based withPgClient API.
+ */
+export { withPgClient } from 'pg-query-context';

package/pg-client.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * pg-client — Re-exports withPgClient from pg-query-context
+ *
+ * This module exists for backwards compatibility. The implementation
+ * lives in pg-query-context which provides both the single-query API
+ * and the callback-based withPgClient API.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withPgClient = void 0;
+var pg_query_context_1 = require("pg-query-context");
+Object.defineProperty(exports, "withPgClient", { enumerable: true, get: function () { return pg_query_context_1.withPgClient; } });

package/pg-settings.d.ts

@@ -0,0 +1,29 @@
+/**
+ * pg-settings — Build pgSettings from resolved API + auth token
+ *
+ * pgSettings are key-value pairs passed to PostgreSQL via SET LOCAL
+ * within each transaction. They carry the JWT claims, role, database_id,
+ * and request_id so that RLS policies and SQL functions can reference
+ * the current user context via `current_setting('jwt.claims.user_id')`.
+ *
+ * This module extracts the pgSettings construction so it's reusable
+ * across the PostGraphile server, LLM sidecar, or any Express service.
+ */
+import type { ApiStructure, ConstructiveAPIToken } from './types';
+export interface PgSettingsInput {
+    /** Resolved API config (provides role names, database_id) */
+    api: ApiStructure;
+    /** Authenticated token (null for anonymous) */
+    token: ConstructiveAPIToken | null;
+    /** Per-request correlation ID */
+    requestId: string;
+    /** Client IP address (from request-ip middleware) */
+    clientIp?: string;
+}
+/**
+ * Build pgSettings from the resolved API + auth token.
+ *
+ * These settings are applied via SET LOCAL in each transaction,
+ * making them available to RLS policies and SQL functions.
+ */
+export declare function buildPgSettings(input: PgSettingsInput): Record<string, string>;

package/pg-settings.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * pg-settings — Build pgSettings from resolved API + auth token
+ *
+ * pgSettings are key-value pairs passed to PostgreSQL via SET LOCAL
+ * within each transaction. They carry the JWT claims, role, database_id,
+ * and request_id so that RLS policies and SQL functions can reference
+ * the current user context via `current_setting('jwt.claims.user_id')`.
+ *
+ * This module extracts the pgSettings construction so it's reusable
+ * across the PostGraphile server, LLM sidecar, or any Express service.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPgSettings = buildPgSettings;
+/**
+ * Build pgSettings from the resolved API + auth token.
+ *
+ * These settings are applied via SET LOCAL in each transaction,
+ * making them available to RLS policies and SQL functions.
+ */
+function buildPgSettings(input) {
+    const { api, token, requestId, clientIp } = input;
+    const settings = {};
+    // Role: from token (authenticated) or api (anonymous fallback)
+    if (token?.user_id) {
+        settings['role'] = api.roleName || 'authenticated';
+        settings['jwt.claims.user_id'] = token.user_id;
+    }
+    else {
+        settings['role'] = api.anonRole || 'anonymous';
+    }
+    // Session claims
+    if (token?.session_id) {
+        settings['jwt.claims.session_id'] = token.session_id;
+    }
+    // Database context
+    if (api.databaseId) {
+        settings['jwt.claims.database_id'] = api.databaseId;
+    }
+    // Distributed tracing
+    settings['request.id'] = requestId;
+    // Client metadata (for audit functions)
+    if (clientIp) {
+        settings['jwt.claims.ip_address'] = clientIp;
+    }
+    return settings;
+}

package/request-id.d.ts

@@ -0,0 +1,14 @@
+/**
+ * request-id — Per-request correlation ID middleware
+ *
+ * Generates a UUID v4 request ID (or uses an incoming X-Request-Id header)
+ * and attaches it to `req.requestId`. This ID propagates through pgSettings
+ * into billing ledger entries and inference logs for distributed tracing.
+ */
+import type { RequestHandler } from 'express';
+/**
+ * Middleware that ensures every request has a correlation ID.
+ *
+ * Priority: `X-Request-Id` header → new UUID v4
+ */
+export declare function requestIdMiddleware(): RequestHandler;

package/request-id.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * request-id — Per-request correlation ID middleware
+ *
+ * Generates a UUID v4 request ID (or uses an incoming X-Request-Id header)
+ * and attaches it to `req.requestId`. This ID propagates through pgSettings
+ * into billing ledger entries and inference logs for distributed tracing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestIdMiddleware = requestIdMiddleware;
+const crypto_1 = require("crypto");
+/**
+ * Middleware that ensures every request has a correlation ID.
+ *
+ * Priority: `X-Request-Id` header → new UUID v4
+ */
+function requestIdMiddleware() {
+    return (req, _res, next) => {
+        req.requestId = (req.get('X-Request-Id') || (0, crypto_1.randomUUID)());
+        next();
+    };
+}

package/types.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Shared types for Constructive Express middleware.
+ *
+ * These types describe the resolved API structure, RLS module, auth settings,
+ * database feature flags, and other config that middleware attaches to the
+ * Express request. Extracted from graphql/server so any Express-based service
+ * (PostGraphile, LLM sidecar, etc.) can share the same context.
+ */
+import type { Pool, PoolClient } from 'pg';
+export interface CorsModuleData {
+    urls: string[];
+}
+export interface PublicKeyChallengeData {
+    schema: string;
+    crypto_network: string;
+    sign_up_with_key: string;
+    sign_in_request_challenge: string;
+    sign_in_record_failure: string;
+    sign_in_with_challenge: string;
+}
+export interface GenericModuleData {
+    [key: string]: unknown;
+}
+export interface DatabaseSettings {
+    enableAggregates: boolean;
+    enablePostgis: boolean;
+    enableSearch: boolean;
+    enableDirectUploads: boolean;
+    enablePresignedUploads: boolean;
+    enableManyToMany: boolean;
+    enableConnectionFilter: boolean;
+    enableLtree: boolean;
+    enableLlm: boolean;
+    enableRealtime: boolean;
+    enableBulk: boolean;
+}
+export interface PubkeyChallengeSettings {
+    schema: string;
+    cryptoNetwork: string;
+    signUpWithKey: string;
+    signInRequestChallenge: string;
+    signInRecordFailure: string;
+    signInWithChallenge: string;
+}
+export interface WebauthnSettings {
+    schema: string;
+    credentialsSchema: string;
+    sessionsSchema: string;
+    sessionSecretsSchema: string;
+    rpId: string;
+    rpName: string;
+    originAllowlist: string[];
+    attestationType: string;
+    requireUserVerification: boolean;
+    residentKey: string;
+    challengeExpirySeconds: number;
+}
+export type ApiModule = {
+    name: 'cors';
+    data: CorsModuleData;
+} | {
+    name: 'pubkey_challenge';
+    data: PublicKeyChallengeData;
+} | {
+    name: string;
+    data?: GenericModuleData;
+};
+export interface RlsModule {
+    authenticate: string;
+    authenticateStrict: string;
+    privateSchema: {
+        schemaName: string;
+    };
+    publicSchema: {
+        schemaName: string;
+    };
+    currentRole: string;
+    currentRoleId: string;
+    currentIpAddress: string;
+    currentUserAgent: string;
+}
+export interface AuthSettings {
+    cookieSecure?: boolean;
+    cookieSamesite?: string;
+    cookieDomain?: string | null;
+    cookieHttponly?: boolean;
+    cookieMaxAge?: string | null;
+    cookiePath?: string;
+    rememberMeDuration?: string | null;
+    enableCaptcha?: boolean;
+    captchaSiteKey?: string | null;
+}
+export interface ApiStructure {
+    apiId?: string;
+    dbname: string;
+    anonRole: string;
+    roleName: string;
+    schema: string[];
+    apiModules: ApiModule[];
+    rlsModule?: RlsModule;
+    domains?: string[];
+    databaseId?: string;
+    isPublic?: boolean;
+    authSettings?: AuthSettings;
+    corsOrigins?: string[];
+    databaseSettings?: DatabaseSettings;
+    pubkeyChallengeSettings?: PubkeyChallengeSettings;
+    webauthnSettings?: WebauthnSettings;
+}
+export type ApiError = {
+    errorHtml: string;
+};
+export type ApiConfigResult = ApiStructure | ApiError | null;
+export type ConstructiveAPIToken = {
+    id?: string;
+    user_id?: string;
+    session_id?: string;
+    access_level?: string;
+    kind?: string;
+    [key: string]: unknown;
+};
+/**
+ * Maps built-in loader names to their resolved types.
+ *
+ * This enables typed access via `useModule`:
+ *   const rls = await ctx.useModule('rlsModule'); // typed as RlsModule | undefined
+ *
+ * Custom loaders (not in this map) return `unknown`.
+ */
+export interface BuiltinModuleMap {
+    rlsModule: RlsModule;
+    corsOrigins: string[];
+    databaseSettings: DatabaseSettings;
+    authSettings: AuthSettings;
+    pubkeyChallengeSettings: PubkeyChallengeSettings;
+    webauthnSettings: WebauthnSettings;
+}
+/**
+ * Callback for executing queries within a tenant-scoped transaction
+ * with proper pgSettings (role, claims, request_id).
+ */
+export type WithPgClient = <T>(fn: (client: PoolClient) => Promise<T>) => Promise<T>;
+/**
+ * The full tenant context attached to `req.constructive` by the middleware.
+ * Any Express-based service can use this to interact with the tenant database.
+ */
+export interface ConstructiveContext {
+    /** Resolved API structure (database, schemas, RLS, feature flags) */
+    api: ApiStructure;
+    /** Authenticated token (null for anonymous requests) */
+    token: ConstructiveAPIToken | null;
+    /** pgSettings for SET LOCAL in tenant transactions */
+    pgSettings: Record<string, string>;
+    /** Database UUID from the API resolver */
+    databaseId: string | null;
+    /** Authenticated user ID from the JWT token */
+    userId: string | null;
+    /** Per-request correlation ID for distributed tracing */
+    requestId: string;
+    /** Tenant database connection pool */
+    pool: Pool;
+    /** Execute a function within a tenant-scoped RLS transaction */
+    withPgClient: WithPgClient;
+    /**
+     * Resolve a per-database module on demand (lazy, cached).
+     *
+     * Only fires the SQL query on the first call per databaseId per TTL window.
+     * Subsequent calls return the cached result instantly.
+     *
+     * Built-in modules are typed:
+     *   const rls = await ctx.useModule('rlsModule');     // RlsModule | undefined
+     *   const auth = await ctx.useModule('authSettings');  // AuthSettings | undefined
+     *
+     * Custom modules return unknown:
+     *   const custom = await ctx.useModule('myModule');    // unknown
+     *
+     * Returns undefined if:
+     *   - No loader registry was provided to the middleware
+     *   - The named loader isn't registered
+     *   - The module isn't provisioned for this database
+     */
+    useModule: {
+        <K extends keyof BuiltinModuleMap>(name: K): Promise<BuiltinModuleMap[K] | undefined>;
+        (name: string): Promise<unknown>;
+    };
+}
+declare global {
+    namespace Express {
+        interface Request {
+            api?: ApiStructure;
+            clientIp?: string;
+            requestId?: string;
+            token?: ConstructiveAPIToken;
+            constructive?: ConstructiveContext;
+        }
+    }
+}

package/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Shared types for Constructive Express middleware.
+ *
+ * These types describe the resolved API structure, RLS module, auth settings,
+ * database feature flags, and other config that middleware attaches to the
+ * Express request. Extracted from graphql/server so any Express-based service
+ * (PostGraphile, LLM sidecar, etc.) can share the same context.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });