@edium/halifax 2.3.0 → 2.4.0

package/dist/core/crudRouter.d.ts

@@ -1,6 +1,7 @@
 import { type AuthContext, type AuthStrategy } from '../auth/AuthStrategy.js';
 import { type CacheStore } from '../core/cache/index.js';
 import { type OpenApiOptions } from '../openapi/index.js';
+import { type GraphQLOptions } from '../graphql/index.js';
 import { type ResourceDefinition } from '../core/types.js';
 import type { HttpRequest, HttpServer } from '../core/types.js';
 import { normalizeError } from '../core/handlerUtils.js';
@@ -40,6 +41,29 @@ export interface TenantOptions {
      * cross-tenant ("god mode") access for callers with no tenant.
      */
     strict?: boolean;
+    /**
+     * Roles or permission slugs whose holders may bypass tenant scoping for **read** operations
+     * (`getOne`, `getMany`, and the query builder), allowing them to see records across all tenants.
+     * Any single match in `auth.roles` or `auth.permissions` grants the bypass.
+     *
+     * When a bypass caller wants to see only one tenant's data they use the normal filter
+     * mechanism — `?companyId=42` on REST or `filter: { companyId: 42 }` in GraphQL.
+     * No special header or query parameter is needed; the tenant field is just another filterable
+     * column from the admin's perspective.
+     *
+     * Write operations (create / update / delete) are **never** bypassed: the tenant value
+     * continues to come from `resolveId`, keeping write provenance tied to auth — never to
+     * client-supplied input. An admin whose token carries no tenant will receive 403 on writes
+     * unless `strict` is `false`.
+     *
+     * Per-resource {@link ResourceDefinition.bypassTenantRoles} takes precedence over this list.
+     *
+     * @example
+     * ```ts
+     * bypassRoles: ['super_admin', 'support:read-all']
+     * ```
+     */
+    bypassRoles?: string[];
 }
 /** Options for {@link registerCrudApi} / {@link createExpressCrudRouter}. */
 export interface CrudApiOptions {
@@ -60,6 +84,20 @@ export interface CrudApiOptions {
      * additional routes: `GET /openapi.json` (raw spec) and `GET /docs` (Swagger UI).
      */
     openapi?: OpenApiOptions;
+    /**
+     * Enable a GraphQL endpoint. GraphQL is **disabled by default** — you must set
+     * `enabled: true` to activate it. When enabled, Halifax registers `POST <path>` (execution)
+     * and optionally `GET <path>` (GraphiQL IDE). The schema is auto-generated from all
+     * resources that have `graphql !== false`. Requires the `graphql` peer dependency.
+     *
+     * See [README_GRAPHQL.md](./README_GRAPHQL.md) for full docs and examples.
+     *
+     * @example
+     * ```ts
+     * graphql: { enabled: true, path: '/graphql', graphiql: true }
+     * ```
+     */
+    graphql?: GraphQLOptions;
     /**
      * API-wide read-through caching. Provide a `store` (defaults to an in-process
      * {@link InMemoryCacheStore}) and/or a default `ttlSeconds` applied to every resource that

package/dist/core/crudRouter.js

@@ -1,6 +1,8 @@
 import { AllowAllAuthStrategy } from '../auth/AuthStrategy.js';
+import { checkRequiredPermissions } from '../auth/strategies/types.js';
 import { createCachingRepository, InMemoryCacheStore } from '../core/cache/index.js';
 import { generateOpenApiSpec, generateDocsHtml } from '../openapi/index.js';
+import { registerGraphqlRoute } from '../graphql/index.js';
 import { defaultCrudPermissions } from '../core/types.js';
 import { ServerError } from '../errors/ServerError.js';
 import { AuthorizationError } from '../errors/AuthorizationError.js';
@@ -84,6 +86,8 @@ function effectiveTenantField(resource, tenant) {
 }
 /** Matches a safe SQL identifier — tenant fields are interpolated into SQL on bulk paths. */
 const safeIdentifier = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/** Read-only actions that admin bypass applies to. Writes always enforce tenant scoping. */
+const READ_ACTIONS = new Set(['readOne', 'readMany', 'readManyWithQueryBuilder']);
 /**
  * Registers all CRUD routes for every resource on the given HTTP server.
  *
@@ -132,10 +136,16 @@ export function registerCrudApi(server, resources, options = {}) {
                 bust
             })
             : repo;
-        const resolveRepo = async (req, auth) => {
+        const resolveRepo = async (req, auth, action) => {
             const bust = cachingEnabled && wantsCacheBust(req, bustHeader);
             if (!tenantField || !options.tenant)
                 return withCache(repository, 'global', bust);
+            // Admin bypass: callers with a privileged role/permission get unscoped reads.
+            // Writes always fall through to resolveId — tenant on writes comes from auth, never bypass.
+            const bypassRoles = resource.bypassTenantRoles ?? options.tenant.bypassRoles ?? [];
+            if (READ_ACTIONS.has(action) && bypassRoles.length > 0 && checkRequiredPermissions(auth, bypassRoles)) {
+                return withCache(repository, 'global', bust);
+            }
             const value = await options.tenant.resolveId({ auth, req, resource });
             if (value === undefined || value === null || value === '') {
                 if (options.tenant.strict !== false)
@@ -199,6 +209,48 @@ export function registerCrudApi(server, resources, options = {}) {
             });
         }
     });
+    // ─── GraphQL endpoint ──────────────────────────────────────────────────────
+    if (options.graphql?.enabled === true) {
+        // Build per-resource contexts carrying the already-resolved resolveRepo closures.
+        // We re-iterate resources to capture the closure variables that were set up above.
+        const graphqlContexts = resources.map((rawResource) => {
+            const resource = normalizeResource(rawResource);
+            const repository = rawResource.repository;
+            const tenantField = effectiveTenantField(resource, options.tenant);
+            const cacheTtl = resource.cache === false
+                ? undefined
+                : (resource.cache?.ttlSeconds ?? options.cache?.ttlSeconds);
+            const cachingEnabled = cacheTtl !== undefined;
+            const withCacheLocal = (repo, scopeKey, bust) => cachingEnabled
+                ? createCachingRepository(repo, {
+                    store: cacheStore,
+                    ttlSeconds: cacheTtl,
+                    namespace: `${resource.name}:${scopeKey}`,
+                    bust
+                })
+                : repo;
+            const resolveRepoLocal = async (req, auth, action) => {
+                const bust = cachingEnabled && wantsCacheBust(req, bustHeader);
+                if (!tenantField || !options.tenant)
+                    return withCacheLocal(repository, 'global', bust);
+                const bypassRoles = resource.bypassTenantRoles ?? options.tenant.bypassRoles ?? [];
+                if (READ_ACTIONS.has(action) && bypassRoles.length > 0 && checkRequiredPermissions(auth, bypassRoles)) {
+                    return withCacheLocal(repository, 'global', bust);
+                }
+                const value = await options.tenant.resolveId({ auth, req, resource });
+                if (value === undefined || value === null || value === '') {
+                    if (options.tenant.strict !== false)
+                        throw new AuthorizationError('No tenant is associated with this request.');
+                    return withCacheLocal(repository, 'global', bust);
+                }
+                return withCacheLocal(repository.withScope({ field: tenantField, value }), String(value), bust);
+            };
+            const hooks = resource.hooks;
+            return { resource, authStrategy, hooks, resolveRepo: resolveRepoLocal };
+        });
+        registerGraphqlRoute(server, graphqlContexts, options.graphql, authStrategy);
+    }
+    // ─── OpenAPI spec + docs ───────────────────────────────────────────────────
     if (options.openapi && options.openapi.enabled !== false) {
         const specPath = options.openapi.specPath ?? '/openapi.json';
         const docsPath = options.openapi.docsPath ?? '/docs';

package/dist/core/handlerUtils.d.ts

@@ -72,5 +72,5 @@ export interface RouteHandlerContext {
     authStrategy: AuthStrategy;
     envelope: string | null;
     hooks: CrudHooks<Record<string, unknown>, Record<string, unknown>, Record<string, unknown>> | undefined;
-    resolveRepo: (req: HttpRequest, auth: AuthContext) => Promise<Repository>;
+    resolveRepo: (req: HttpRequest, auth: AuthContext, action: CrudAction) => Promise<Repository>;
 }

package/dist/core/handlers/create.js

@@ -3,7 +3,7 @@ export function registerCreate(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('POST', basePath, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'create', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'create');
         const idempotencyKey = getHeaderValue(req, 'idempotency-key');
         const createOptions = idempotencyKey ? { idempotencyKey } : undefined;
         const hookCtx = { auth, resource, req };

package/dist/core/handlers/deleteMany.js

@@ -6,7 +6,7 @@ export function registerDeleteMany(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('DELETE', basePath, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'deleteMany', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'deleteMany');
         if (!repo.deleteMany)
             throw new NotImplementedError('This resource does not support deleteMany.');
         const hookCtx = { auth, resource, req };

package/dist/core/handlers/deleteOne.js

@@ -4,7 +4,7 @@ export function registerDeleteOne(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('DELETE', `${basePath}/:id`, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'deleteOne', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'deleteOne');
         const id = parseId(req.params['id']);
         const hookCtx = { auth, resource, req };
         if (hooks?.beforeDeleteOne)

package/dist/core/handlers/query.js

@@ -5,7 +5,7 @@ export function registerQuery(server, basePath, queryBuilderPath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('POST', `${basePath}/${queryBuilderPath}`, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'readManyWithQueryBuilder', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'readManyWithQueryBuilder');
         if (!repo.executeQuery)
             throw new NotImplementedError('This resource does not support the query builder.');
         const hookCtx = { auth, resource, req };

package/dist/core/handlers/readMany.js

@@ -4,7 +4,7 @@ export function registerReadMany(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('GET', basePath, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'readMany', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'readMany');
         const hookCtx = { auth, resource, req };
         const parsedOptions = parseListOptions(req.query, resource);
         const listOptions = await applyHook(hooks?.beforeReadMany, parsedOptions, hookCtx);

package/dist/core/handlers/readOne.js

@@ -5,7 +5,7 @@ export function registerReadOne(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('GET', `${basePath}/:id`, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'readOne', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'readOne');
         const id = parseId(req.params['id']);
         const hookCtx = { auth, resource, req };
         if (hooks?.beforeReadOne)

package/dist/core/handlers/updateMany.js

@@ -6,7 +6,7 @@ export function registerUpdateMany(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('PATCH', basePath, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'updateMany', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'updateMany');
         if (!repo.updateMany)
             throw new NotImplementedError('This resource does not support updateMany.');
         const hookCtx = { auth, resource, req };

package/dist/core/handlers/updateOne.js

@@ -4,7 +4,7 @@ export function registerUpdateOne(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('PATCH', `${basePath}/:id`, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'updateOne', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'updateOne');
         const id = parseId(req.params['id']);
         const hookCtx = { auth, resource, req };
         const rawBody = filterWritableFields(resource, (req.body ?? {}), auth);

package/dist/core/handlers/upsertOne.js

@@ -4,7 +4,7 @@ export function registerUpsertOne(server, basePath, ctx) {
     const { resource, authStrategy, envelope, hooks, resolveRepo } = ctx;
     server.registerRoute('PUT', `${basePath}/:id`, wrap(async (req, res) => {
         const auth = await authorizeRequest(req, resource, 'upsertOne', authStrategy);
-        const repo = await resolveRepo(req, auth);
+        const repo = await resolveRepo(req, auth, 'upsertOne');
         if (!repo.upsertOne)
             throw new NotImplementedError('This resource does not support upsert.');
         const id = parseId(req.params['id']);

package/dist/core/types.d.ts

@@ -389,6 +389,28 @@ export interface ResourceDefinition<TRecord = unknown, TCreate = Partial<TRecord
      * `false` to explicitly disable caching for this resource even when a default is configured.
      */
     cache?: ResourceCacheConfig | false;
+    /**
+     * Controls whether this resource is exposed through the GraphQL endpoint.
+     * Set to `false` to exclude this resource from the generated GraphQL schema entirely.
+     * Defaults to `true` when GraphQL is enabled on the API.
+     */
+    graphql?: boolean;
+    /**
+     * Roles or permission slugs whose holders may bypass tenant scoping for **read** operations
+     * on this resource, allowing them to see records across all tenants. Any single match in
+     * `auth.roles` or `auth.permissions` grants the bypass.
+     *
+     * Bypass callers receive all records on reads. To narrow to a single tenant they use the
+     * standard filter mechanism (`?companyId=42` on REST, `filter: { companyId: 42 }` in
+     * GraphQL) — the tenant field is just another filterable column from their perspective.
+     *
+     * Write operations (create / update / delete) are **never** bypassed — tenant value on writes
+     * always comes from `resolveId` (the auth token), not from the bypass path.
+     *
+     * Overrides {@link TenantOptions.bypassRoles} for this resource. Set to `[]` to disable
+     * bypass on this resource even when a global `bypassRoles` is configured.
+     */
+    bypassTenantRoles?: string[];
     /**
      * Wrap every success response body for this resource under a single key
      * (e.g. `'data'` →

package/dist/graphql/graphiql.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates an HTML page that renders the GraphiQL IDE, loading assets from unpkg.com CDN.
+ * The GraphQL endpoint URL is embedded so GraphiQL points at the correct server path.
+ */
+export declare function generateGraphiQLHtml(graphqlPath: string, title: string): string;

package/dist/graphql/graphiql.js

@@ -0,0 +1,29 @@
+/**
+ * Generates an HTML page that renders the GraphiQL IDE, loading assets from unpkg.com CDN.
+ * The GraphQL endpoint URL is embedded so GraphiQL points at the correct server path.
+ */
+export function generateGraphiQLHtml(graphqlPath, title) {
+    const escapedPath = JSON.stringify(graphqlPath);
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${title}</title>
+  <link href="https://unpkg.com/graphiql/graphiql.min.css" rel="stylesheet" />
+  <style>body { margin: 0; }</style>
+</head>
+<body>
+  <div id="graphiql" style="height:100vh;"></div>
+  <script crossorigin src="https://unpkg.com/react/umd/react.production.min.js"></script>
+  <script crossorigin src="https://unpkg.com/react-dom/umd/react-dom.production.min.js"></script>
+  <script src="https://unpkg.com/graphiql/graphiql.min.js" type="application/javascript"></script>
+  <script>
+    var fetcher = GraphiQL.createFetcher({ url: ${escapedPath} });
+    ReactDOM.createRoot(document.getElementById('graphiql')).render(
+      React.createElement(GraphiQL, { fetcher: fetcher })
+    );
+  </script>
+</body>
+</html>`;
+}

package/dist/graphql/index.d.ts

@@ -0,0 +1,4 @@
+export type { GraphQLOptions, GraphQLResourceContext, GraphQLResolverContext } from './types.js';
+export { buildGraphQLSchema } from './schema.js';
+export { registerGraphqlRoute } from './registerGraphqlRoute.js';
+export { generateGraphiQLHtml } from './graphiql.js';

package/dist/graphql/index.js

@@ -0,0 +1,3 @@
+export { buildGraphQLSchema } from './schema.js';
+export { registerGraphqlRoute } from './registerGraphqlRoute.js';
+export { generateGraphiQLHtml } from './graphiql.js';

package/dist/graphql/registerGraphqlRoute.d.ts

@@ -0,0 +1,10 @@
+import type { GraphQLOptions, GraphQLResourceContext } from './types.js';
+import type { AuthStrategy } from '../auth/strategies/types.js';
+import type { HttpServer } from '../core/types.js';
+/**
+ * Registers the `POST /graphql` execution endpoint and optionally the `GET /graphql`
+ * GraphiQL IDE page on the given HTTP server.
+ *
+ * The schema is built once at registration time from the provided resource contexts.
+ */
+export declare function registerGraphqlRoute(server: HttpServer, contexts: GraphQLResourceContext[], options: GraphQLOptions, authStrategy: AuthStrategy): void;

package/dist/graphql/registerGraphqlRoute.js

@@ -0,0 +1,79 @@
+import { graphql, parse, validate } from 'graphql';
+import { buildGraphQLSchema } from './schema.js';
+import { generateGraphiQLHtml } from './graphiql.js';
+import { sendError } from '../core/handlerUtils.js';
+/**
+ * Registers the `POST /graphql` execution endpoint and optionally the `GET /graphql`
+ * GraphiQL IDE page on the given HTTP server.
+ *
+ * The schema is built once at registration time from the provided resource contexts.
+ */
+export function registerGraphqlRoute(server, contexts, options, authStrategy) {
+    if (options.enabled === false)
+        return;
+    const path = options.path ?? '/graphql';
+    const graphiqlEnabled = options.graphiql !== false;
+    const requireAuth = options.requireAuth === true;
+    const title = options.title ?? 'Halifax GraphQL';
+    const schema = buildGraphQLSchema(contexts);
+    const graphiqlHtml = graphiqlEnabled ? generateGraphiQLHtml(path, title) : null;
+    // ─── POST /graphql — execution endpoint ─────────────────────────────────
+    server.registerRoute('POST', path, async (req, res) => {
+        try {
+            if (requireAuth)
+                await authStrategy.authenticate(req);
+            const body = (req.body ?? {});
+            const source = body.query ?? '';
+            if (!source.trim()) {
+                await res.status(400).json({
+                    errors: [{ message: 'GraphQL request must include a query.' }]
+                });
+                return;
+            }
+            // Parse and validate before executing so syntax errors surface cleanly.
+            let document;
+            try {
+                document = parse(source);
+            }
+            catch (syntaxError) {
+                await res.status(400).json({
+                    errors: [
+                        { message: syntaxError instanceof Error ? syntaxError.message : 'Syntax error.' }
+                    ]
+                });
+                return;
+            }
+            const validationErrors = validate(schema, document);
+            if (validationErrors.length) {
+                await res.status(400).json({ errors: validationErrors.map((e) => ({ message: e.message })) });
+                return;
+            }
+            const result = await graphql({
+                schema,
+                source,
+                variableValues: body.variables,
+                operationName: body.operationName,
+                contextValue: { req }
+            });
+            res.setHeader?.('Content-Type', 'application/json');
+            await res.status(200).json(result);
+        }
+        catch (error) {
+            await sendError(error, res);
+        }
+    });
+    // ─── GET /graphql — GraphiQL IDE ─────────────────────────────────────────
+    if (graphiqlEnabled && graphiqlHtml) {
+        server.registerRoute('GET', path, async (req, res) => {
+            try {
+                if (requireAuth)
+                    await authStrategy.authenticate(req);
+                res.setHeader?.('Content-Type', 'text/html; charset=utf-8');
+                res.send?.(graphiqlHtml);
+            }
+            catch (error) {
+                await sendError(error, res);
+            }
+        });
+    }
+}

package/dist/graphql/scalars.d.ts

@@ -0,0 +1,6 @@
+import { GraphQLScalarType } from 'graphql';
+/**
+ * Custom `JSON` scalar that accepts any JSON-serializable value.
+ * Used for filter `value1`/`value2` fields in QueryFilterInput and for `object` field types.
+ */
+export declare const GraphQLJSON: GraphQLScalarType<unknown, unknown>;

package/dist/graphql/scalars.js

@@ -0,0 +1,32 @@
+import { GraphQLScalarType, Kind } from 'graphql';
+function parseLiteralToValue(ast) {
+    switch (ast.kind) {
+        case Kind.STRING:
+            return ast.value;
+        case Kind.BOOLEAN:
+            return ast.value;
+        case Kind.INT:
+            return parseInt(ast.value, 10);
+        case Kind.FLOAT:
+            return parseFloat(ast.value);
+        case Kind.NULL:
+            return null;
+        case Kind.LIST:
+            return ast.values.map(parseLiteralToValue);
+        case Kind.OBJECT:
+            return Object.fromEntries(ast.fields.map((f) => [f.name.value, parseLiteralToValue(f.value)]));
+        default:
+            return null;
+    }
+}
+/**
+ * Custom `JSON` scalar that accepts any JSON-serializable value.
+ * Used for filter `value1`/`value2` fields in QueryFilterInput and for `object` field types.
+ */
+export const GraphQLJSON = new GraphQLScalarType({
+    name: 'JSON',
+    description: 'Arbitrary JSON value (string, number, boolean, null, array, or object).',
+    serialize: (value) => value,
+    parseValue: (value) => value,
+    parseLiteral: parseLiteralToValue
+});

package/dist/graphql/schema.d.ts

@@ -0,0 +1,3 @@
+import { GraphQLSchema } from 'graphql';
+import type { GraphQLResourceContext } from './types.js';
+export declare function buildGraphQLSchema(contexts: GraphQLResourceContext[]): GraphQLSchema;