@degenerate/endpoints 0.1.7 → 0.4.0

package/dist/examples/express-server/app.d.ts

@@ -1,3 +1,21 @@
-declare const app: import("express-serve-static-core").Express;
-export default app;
+import express, { type Express } from 'express';
+import { AuthorizedAuthorities } from '@degenerate/generic';
+import { ShareDataManager } from '@degenerate/sharedata';
+export interface CreateAppResult {
+    app: Express;
+    authorizedAuthorities: AuthorizedAuthorities;
+    shareDataManager: ShareDataManager;
+}
+/**
+ * Builds a fresh Express app with all SAFE routes wired in. Returns the app
+ * along with the shared `ShareDataManager` instance — handed back so callers
+ * (e.g. `createSafeServer` for realtime attachment) can subscribe to its
+ * events without reaching into `app.locals`.
+ *
+ * Route handlers access the manager via `req.app.get('shareDataManager')`,
+ * matching the existing `authorizedAuthorities` pattern.
+ */
+export declare function createApp(): CreateAppResult;
+declare const _default: express.Express;
+export default _default;
 //# sourceMappingURL=app.d.ts.map

package/dist/examples/express-server/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/examples/express-server/app.ts"],"names":[],"mappings":"AAeA,QAAA,MAAM,GAAG,6CAAY,CAAC;AAsBtB,eAAe,GAAG,CAAC"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../../src/examples/express-server/app.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EAAE,KAAK,OAAO,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAYzD,MAAM,WAAW,eAAe;IAC5B,GAAG,EAAE,OAAO,CAAC;IACb,qBAAqB,EAAE,qBAAqB,CAAC;IAC7C,gBAAgB,EAAE,gBAAgB,CAAC;CACtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,IAAI,eAAe,CA6B3C;;AAKD,wBAAmC"}

package/dist/examples/express-server/app.js

@@ -3,7 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApp = createApp;
 const express_1 = __importDefault(require("express"));
+const generic_1 = require("@degenerate/generic");
+const sharedata_1 = require("@degenerate/sharedata");
 //#region Route Imports
 const authorities_routes_1 = require("../../routes/authorities.routes");
 const events_routes_1 = require("../../routes/events.routes");
@@ -11,25 +14,43 @@ const functions_routes_1 = require("../../routes/functions.routes");
 const rules_routes_1 = require("../../routes/rules.routes");
 const share_data_routes_1 = require("../../routes/share-data.routes");
 const validation_routes_1 = require("../../routes/validation.routes");
-const generic_1 = require("@degenerate/generic");
 const cors_1 = require("../../cors");
-//#endregion Route Imports
-// create the express application
-const app = (0, express_1.default)();
-app.use(express_1.default.json());
-const authorizedAuthorities = new generic_1.AuthorizedAuthorities();
-// Initialize the authorized authorities here if needed
-// e.g., authorizedAuthorities.addAuthorizedJWTAuthority(...);
-// Make the instance available throughout the app
-app.set('authorizedAuthorities', authorizedAuthorities);
-// Make sure you enable whatever middleware you need here
-app.use('/authorities', authorities_routes_1.authorities); // add the authorities routes
-app.use('/events', events_routes_1.events); // add the events routes
-app.use('/functions', functions_routes_1.functions); // add the functions routes
-app.use('/rules', rules_routes_1.rules); // add the rules routes
-app.use('/share-data', share_data_routes_1.shareData); // add the share data routes
-app.use('/validation', validation_routes_1.validation); // add the validation routes
-app.use(cors_1.unauthorizedHandler); // the unauthorized handler should be the first error handler
-app.use(cors_1.badRequestHandler); // the bad request handler should be the second error handler
-app.use(cors_1.allErrorHandler); // the all error handler catches all remaining errors
-exports.default = app;
+const openapi_1 = require("../../openapi");
+/**
+ * Builds a fresh Express app with all SAFE routes wired in. Returns the app
+ * along with the shared `ShareDataManager` instance — handed back so callers
+ * (e.g. `createSafeServer` for realtime attachment) can subscribe to its
+ * events without reaching into `app.locals`.
+ *
+ * Route handlers access the manager via `req.app.get('shareDataManager')`,
+ * matching the existing `authorizedAuthorities` pattern.
+ */
+function createApp() {
+    const app = (0, express_1.default)();
+    app.use(express_1.default.json());
+    const authorizedAuthorities = new generic_1.AuthorizedAuthorities();
+    const shareDataManager = new sharedata_1.ShareDataManager();
+    app.set('authorizedAuthorities', authorizedAuthorities);
+    app.set('shareDataManager', shareDataManager);
+    // Public, unauthenticated machine-readable API description. Generated once
+    // from the same Zod schemas the routes validate against; no auth so tooling
+    // (codegen, Swagger UI, contract tests) can fetch it freely.
+    const openApiDocument = (0, openapi_1.buildOpenApiDocument)();
+    app.get('/openapi.json', (_req, res) => {
+        res.status(200).json(openApiDocument);
+    });
+    app.use('/authorities', authorities_routes_1.authorities);
+    app.use('/events', events_routes_1.events);
+    app.use('/functions', functions_routes_1.functions);
+    app.use('/rules', rules_routes_1.rules);
+    app.use('/share-data', share_data_routes_1.shareData);
+    app.use('/validation', validation_routes_1.validation);
+    app.use(cors_1.unauthorizedHandler);
+    app.use(cors_1.badRequestHandler);
+    app.use(cors_1.allErrorHandler);
+    return { app, authorizedAuthorities, shareDataManager };
+}
+// Back-compat: tests and existing callers import the default app singleton.
+// New code should prefer `createApp()` so each instance is isolated.
+const defaultInstance = createApp();
+exports.default = defaultInstance.app;

package/dist/examples/express-server/authenticate-realtime.d.ts

@@ -0,0 +1,27 @@
+import type { AuthenticateUpgrade } from '@degenerate/realtime';
+/**
+ * Context attached to every accepted WebSocket connection. Replace the
+ * placeholder fields with whatever your application needs to authorize
+ * subsequent messages (subject, scopes, tenant id, etc.).
+ */
+export interface ExampleRealtimeContext {
+    subject: string;
+}
+/**
+ * Example upgrade authenticator. Accepts every connection with a synthetic
+ * subject — adequate for demos and integration tests, not for production.
+ *
+ * To wire real JWT auth, replace the body with something like:
+ *
+ *   import { ... } from '@degenerate/generic';
+ *   const token = extractTokenFromHeaderOrQuery(req);
+ *   if (!token) return null;
+ *   const payload = await verifyJwt(token, authorizedAuthorities);
+ *   return payload ? { subject: payload.sub } : null;
+ *
+ * `validateJWTShareData` in `cors/authority/jwt/` is the HTTP-side equivalent
+ * — reuse the same key resolution + claim checks here so HTTP and WS share an
+ * authorization model.
+ */
+export declare const exampleAuthenticate: AuthenticateUpgrade<ExampleRealtimeContext>;
+//# sourceMappingURL=authenticate-realtime.d.ts.map

package/dist/examples/express-server/authenticate-realtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticate-realtime.d.ts","sourceRoot":"","sources":["../../../src/examples/express-server/authenticate-realtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACnC,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,EAAE,mBAAmB,CAAC,sBAAsB,CAI3E,CAAC"}

package/dist/examples/express-server/authenticate-realtime.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exampleAuthenticate = void 0;
+/**
+ * Example upgrade authenticator. Accepts every connection with a synthetic
+ * subject — adequate for demos and integration tests, not for production.
+ *
+ * To wire real JWT auth, replace the body with something like:
+ *
+ *   import { ... } from '@degenerate/generic';
+ *   const token = extractTokenFromHeaderOrQuery(req);
+ *   if (!token) return null;
+ *   const payload = await verifyJwt(token, authorizedAuthorities);
+ *   return payload ? { subject: payload.sub } : null;
+ *
+ * `validateJWTShareData` in `cors/authority/jwt/` is the HTTP-side equivalent
+ * — reuse the same key resolution + claim checks here so HTTP and WS share an
+ * authorization model.
+ */
+const exampleAuthenticate = (_req) => {
+    return { subject: 'example-anonymous' };
+};
+exports.exampleAuthenticate = exampleAuthenticate;

package/dist/examples/express-server/server.d.ts

@@ -1,2 +1,33 @@
-export {};
+import { type Server as HttpServer } from 'http';
+import type { Express } from 'express';
+import { ShareDataManager } from '@degenerate/sharedata';
+import { type RealtimeServerHandle } from '@degenerate/realtime';
+export interface SafeServerHandle {
+    /** The Express application — the same instance imported from `./app`. */
+    readonly app: Express;
+    /** The underlying Node HTTP server. Call `.listen()` to start accepting. */
+    readonly httpServer: HttpServer;
+    /** ShareDataManager broadcasting to subscribed WebSocket clients. */
+    readonly manager: ShareDataManager;
+    /** Realtime websocket handle. Call `.close()` during shutdown. */
+    readonly realtime: RealtimeServerHandle;
+    /** Convenience: cleanly stop realtime + close the HTTP server. */
+    close(): Promise<void>;
+}
+/**
+ * Builds the example SAFE server: the existing Express app wrapped in a Node
+ * HTTP server, with the realtime WebSocket transport attached at `/realtime`.
+ * Returns handles for caller-controlled `listen()` and shutdown so this is
+ * safe to use from tests as well as a `bin/` entry point.
+ *
+ * The returned `manager` is the one wired to the realtime broadcast loop and
+ * also the one routes resolve via `req.app.get('shareDataManager')`. HTTP
+ * route mutations therefore appear as `transaction` frames on the websocket.
+ *
+ * `propose` is wired to the id-based function resolver: any `IShareFunction`
+ * registered on a ShareData with an `id` becomes addressable by clients via
+ * the `functionId` field in a `propose` message. Functions without an `id`
+ * remain invisible to the wire — useful for purely-internal functions.
+ */
+export declare function createSafeServer(): SafeServerHandle;
 //# sourceMappingURL=server.d.ts.map

package/dist/examples/express-server/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/examples/express-server/server.ts"],"names":[],"mappings":""}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/examples/express-server/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AAC/D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAGH,KAAK,oBAAoB,EAC5B,MAAM,sBAAsB,CAAC;AAI9B,MAAM,WAAW,gBAAgB;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,kEAAkE;IAClE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,IAAI,gBAAgB,CA6BnD"}

package/dist/examples/express-server/server.js

@@ -1,9 +1,63 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-const app_1 = __importDefault(require("./app"));
-app_1.default.listen(3000, () => {
-    console.log('Server is running on port 3000');
-});
+exports.createSafeServer = createSafeServer;
+const http_1 = require("http");
+const realtime_1 = require("@degenerate/realtime");
+const app_1 = require("./app");
+const authenticate_realtime_1 = require("./authenticate-realtime");
+/**
+ * Builds the example SAFE server: the existing Express app wrapped in a Node
+ * HTTP server, with the realtime WebSocket transport attached at `/realtime`.
+ * Returns handles for caller-controlled `listen()` and shutdown so this is
+ * safe to use from tests as well as a `bin/` entry point.
+ *
+ * The returned `manager` is the one wired to the realtime broadcast loop and
+ * also the one routes resolve via `req.app.get('shareDataManager')`. HTTP
+ * route mutations therefore appear as `transaction` frames on the websocket.
+ *
+ * `propose` is wired to the id-based function resolver: any `IShareFunction`
+ * registered on a ShareData with an `id` becomes addressable by clients via
+ * the `functionId` field in a `propose` message. Functions without an `id`
+ * remain invisible to the wire — useful for purely-internal functions.
+ */
+function createSafeServer() {
+    const { app, shareDataManager: manager } = (0, app_1.createApp)();
+    const httpServer = (0, http_1.createServer)(app);
+    const realtime = (0, realtime_1.attachRealtimeServer)({
+        server: httpServer,
+        manager,
+        authenticate: authenticate_realtime_1.exampleAuthenticate,
+        path: '/realtime',
+        resolveFunction: (0, realtime_1.createIdBasedFunctionResolver)(manager),
+    });
+    let closed = false;
+    return {
+        app,
+        httpServer,
+        manager,
+        realtime,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            await realtime.close();
+            // `httpServer.close()` errors if the server is already closed.
+            // The realtime handle may have already terminated all WS sockets,
+            // but the HTTP listener still needs to be stopped. Swallow the
+            // "not running" error so close() is idempotent.
+            await new Promise((resolve) => {
+                httpServer.close(() => resolve());
+            });
+        },
+    };
+}
+// When run directly (e.g. `node dist/examples/express-server/server.js`),
+// start the server on port 3000. Tests should call `createSafeServer()` and
+// drive `.httpServer.listen(0, ...)` themselves.
+if (require.main === module) {
+    const handle = createSafeServer();
+    handle.httpServer.listen(3000, () => {
+        // eslint-disable-next-line no-console
+        console.log('SAFE example server listening on :3000 (WS at /realtime)');
+    });
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './cors';
+export * from './openapi';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 // This is the main file for the package
 __exportStar(require("./cors"), exports);
+__exportStar(require("./openapi"), exports);

package/dist/openapi/build-openapi-document.d.ts

@@ -0,0 +1,27 @@
+import type { OperationDescriptor } from './types';
+export interface OpenApiInfo {
+    title: string;
+    version: string;
+    description?: string;
+}
+/**
+ * Minimal structural shape of the emitted document. Component and path values
+ * are JSON Schema / OpenAPI fragments produced by Zod, so they are typed
+ * loosely rather than re-modeling the whole OpenAPI 3.0 type tree.
+ */
+export interface OpenApiDocument {
+    openapi: string;
+    info: OpenApiInfo;
+    components: {
+        securitySchemes: Record<string, unknown>;
+        schemas: Record<string, unknown>;
+    };
+    paths: Record<string, Record<string, unknown>>;
+}
+/**
+ * Build an OpenAPI 3.0 document from the operation descriptors. Pure function:
+ * same input, same output, no side effects — so it can be computed once at
+ * server start and served as static JSON.
+ */
+export declare function buildOpenApiDocument(operations?: OperationDescriptor[], info?: OpenApiInfo): OpenApiDocument;
+//# sourceMappingURL=build-openapi-document.d.ts.map

package/dist/openapi/build-openapi-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-openapi-document.d.ts","sourceRoot":"","sources":["../../src/openapi/build-openapi-document.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAOnD,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE;QACR,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,CAAC;IACF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAClD;AAqOD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAChC,UAAU,GAAE,mBAAmB,EAAkB,EACjD,IAAI,GAAE,WAA0B,GACjC,eAAe,CAuBjB"}

package/dist/openapi/build-openapi-document.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOpenApiDocument = buildOpenApiDocument;
+const zod_1 = require("zod");
+const operations_1 = require("./operations");
+const domain_schemas_1 = require("./domain-schemas");
+/** Stable component names for the raw `@degenerate/generic` domain schemas. */
+const domainNames = new Map(domain_schemas_1.domainComponentNames);
+const DEFAULT_INFO = {
+    title: 'SAFE Endpoints API',
+    version: '1.0.0',
+    description: 'HTTP surface for the SAFE platform. Request and response schemas are ' +
+        'generated from the same Zod schemas the routes validate against.',
+};
+const STATUS_DESCRIPTIONS = {
+    200: 'Success',
+    400: 'Validation error',
+    403: 'Unauthorized',
+    404: 'Not found',
+    500: 'Internal server error',
+    501: 'Not implemented',
+};
+const statusDescription = (code) => STATUS_DESCRIPTIONS[code] ?? `Status ${code}`;
+/** Names of `{param}` placeholders in an OpenAPI path template, in order. */
+const pathParamNames = (path) => {
+    const names = [];
+    const matcher = /\{([^}]+)\}/g;
+    let match;
+    while ((match = matcher.exec(path)) !== null) {
+        names.push(match[1]);
+    }
+    return names;
+};
+const componentRef = (name) => ({
+    $ref: `#/components/schemas/${name}`,
+});
+/**
+ * Prefix of the `$ref`s Zod emits into its internal `__shared` defs bucket when
+ * a non-registered sub-schema is reused across two or more registered roots.
+ */
+const SHARED_REF_PREFIX = '#/components/schemas/__shared#/definitions/';
+/**
+ * Inline any `__shared` `$ref` with the actual sub-schema it points at, leaving
+ * every real `#/components/schemas/<Name>` `$ref` untouched. Returns a fresh
+ * deep copy — never mutates the input.
+ *
+ * Why this is needed: `IShareRuleAppliedSchema` is `IShareRuleSchema.extend(...)`,
+ * so both share the very same `z.array(IConditionSchema)` instance for
+ * `currentDataConditions` / `proposedDataConditions`. When several rule schemas
+ * are registered together, Zod hoists that shared array into a `__shared`
+ * defs entry and points to it with a `__shared#/definitions/schemaN` `$ref`,
+ * which is not a resolvable OpenAPI component. Inlining the (small, acyclic)
+ * shared sub-schema yields a clean spec; the genuinely recursive schemas
+ * (`ShareRule` ↔ `Condition`) stay as proper component `$ref`s because they are
+ * registered.
+ */
+const inlineSharedRefs = (value, defs, active) => {
+    if (Array.isArray(value)) {
+        return value.map((item) => inlineSharedRefs(item, defs, active));
+    }
+    if (value && typeof value === 'object') {
+        const obj = value;
+        const ref = obj.$ref;
+        if (typeof ref === 'string' && ref.startsWith(SHARED_REF_PREFIX)) {
+            const defName = ref.slice(SHARED_REF_PREFIX.length);
+            if (active.has(defName)) {
+                throw new Error(`Cyclic __shared definition while inlining: ${defName}`);
+            }
+            if (!(defName in defs)) {
+                throw new Error(`Unresolved __shared definition: ${defName}`);
+            }
+            active.add(defName);
+            const resolved = inlineSharedRefs(defs[defName], defs, active);
+            active.delete(defName);
+            return resolved;
+        }
+        const out = {};
+        for (const [key, val] of Object.entries(obj)) {
+            out[key] = inlineSharedRefs(val, defs, active);
+        }
+        return out;
+    }
+    return value;
+};
+/** Collect distinct schema instances (request + every response) in encounter order. */
+const collectSchemas = (operations) => {
+    const seen = new Set();
+    const distinct = [];
+    const add = (schema) => {
+        if (schema && !seen.has(schema)) {
+            seen.add(schema);
+            distinct.push(schema);
+        }
+    };
+    for (const op of operations) {
+        add(op.request);
+        for (const schema of Object.values(op.response)) {
+            add(schema);
+        }
+    }
+    return distinct;
+};
+/**
+ * Register each distinct schema under a stable component name, convert the
+ * whole registry to OpenAPI-3.0 JSON Schema in one pass, and return both the
+ * `components.schemas` map and the schema→name lookup used to build `$ref`s.
+ *
+ * One pass with `io: 'output'` is correct for both request and response
+ * positions here because no SAFE schema uses a transform / default / coercion —
+ * so a schema's input and output JSON Schema are identical. Conversion via the
+ * registry overload makes a schema reused across operations (or nested inside a
+ * response envelope) emit as a single `$ref`'d component automatically.
+ */
+const buildComponents = (distinct) => {
+    const registry = zod_1.z.registry();
+    const nameBySchema = new Map();
+    const usedNames = new Set();
+    let autoCounter = 0;
+    for (const schema of distinct) {
+        const metaId = schema.meta()?.id ?? domainNames.get(schema);
+        let name = metaId ?? `Component${++autoCounter}`;
+        // Defensive: distinct schemas must map to distinct component names.
+        while (usedNames.has(name)) {
+            name = `${name}_${++autoCounter}`;
+        }
+        usedNames.add(name);
+        nameBySchema.set(schema, name);
+        registry.add(schema, { id: name });
+    }
+    const { schemas } = zod_1.z.toJSONSchema(registry, {
+        target: 'openapi-3.0',
+        io: 'output',
+        unrepresentable: 'any',
+        uri: (id) => `#/components/schemas/${id}`,
+    });
+    // Zod parks sub-schemas reused across registered roots in a `__shared`
+    // bucket; inline those back into the components and drop the bucket so every
+    // remaining `$ref` resolves to a real component. See `inlineSharedRefs`.
+    const sharedDefs = schemas.__shared?.definitions ?? {};
+    // Strip the non-OpenAPI `$id` Zod stamps on each component; `$ref`s between
+    // components are unaffected.
+    const cleaned = {};
+    for (const [name, schema] of Object.entries(schemas)) {
+        if (name === '__shared') {
+            continue;
+        }
+        const inlined = inlineSharedRefs(schema, sharedDefs, new Set());
+        const { $id, ...rest } = inlined;
+        void $id;
+        cleaned[name] = rest;
+    }
+    return { schemas: cleaned, nameBySchema };
+};
+const buildPaths = (operations, nameBySchema) => {
+    const paths = {};
+    for (const op of operations) {
+        const pathItem = paths[op.path] ?? (paths[op.path] = {});
+        const responses = {};
+        for (const [status, schema] of Object.entries(op.response)) {
+            responses[status] = {
+                description: statusDescription(Number(status)),
+                content: { 'application/json': { schema: componentRef(nameBySchema.get(schema)) } },
+            };
+        }
+        const operationObject = {
+            summary: op.summary,
+            description: op.security === 'public'
+                ? 'Public — no authentication required.'
+                : `Requires a valid JWT for the ${op.security} audience.`,
+            security: op.security === 'public' ? [] : [{ bearerAuth: [] }],
+            responses,
+        };
+        if (op.deprecated) {
+            operationObject.deprecated = true;
+        }
+        const params = pathParamNames(op.path);
+        if (params.length > 0) {
+            operationObject.parameters = params.map((name) => ({
+                name,
+                in: 'path',
+                required: true,
+                schema: { type: 'string' },
+            }));
+        }
+        if (op.request) {
+            operationObject.requestBody = {
+                required: true,
+                content: {
+                    'application/json': { schema: componentRef(nameBySchema.get(op.request)) },
+                },
+            };
+        }
+        pathItem[op.method] = operationObject;
+    }
+    return paths;
+};
+/**
+ * Build an OpenAPI 3.0 document from the operation descriptors. Pure function:
+ * same input, same output, no side effects — so it can be computed once at
+ * server start and served as static JSON.
+ */
+function buildOpenApiDocument(operations = operations_1.operations, info = DEFAULT_INFO) {
+    const { schemas, nameBySchema } = buildComponents(collectSchemas(operations));
+    const paths = buildPaths(operations, nameBySchema);
+    return {
+        openapi: '3.0.3',
+        info,
+        components: {
+            securitySchemes: {
+                bearerAuth: {
+                    type: 'http',
+                    scheme: 'bearer',
+                    bearerFormat: 'JWT',
+                    description: 'JWT bearer token. The token audience (aud) selects which route group it ' +
+                        'authorizes: AUTHORITIES, EVENTS, FUNCTIONS, RULES, or SHAREDATA. Operations ' +
+                        'on /share-data additionally enforce a per-resource (BOLA) check.',
+                },
+            },
+            schemas,
+        },
+        paths,
+    };
+}

package/dist/openapi/domain-schemas.d.ts

@@ -0,0 +1,16 @@
+import type { z } from 'zod';
+/**
+ * Stable OpenAPI component names for the centralized request/domain schemas in
+ * `@degenerate/generic`, keyed by the **raw** schema instance.
+ *
+ * Keyed by the raw instance (not a `.meta()` clone) on purpose: several rule
+ * schemas are recursive (`IShareRuleSchema` ↔ `IConditionSchema`, and
+ * `IShareRuleGroupSchema` via `z.lazy`), and those `z.lazy` thunks resolve to
+ * the raw generic instances. The generator must register the very instances
+ * the schema graph references, otherwise the recursive sub-schemas have no
+ * component id and Zod hoists them into a malformed shared-defs bucket. Every
+ * recursive schema below is also mounted as a `/validation` request body, so
+ * registering these names makes the whole graph resolve to clean `$ref`s.
+ */
+export declare const domainComponentNames: ReadonlyArray<readonly [z.ZodType, string]>;
+//# sourceMappingURL=domain-schemas.d.ts.map

package/dist/openapi/domain-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain-schemas.d.ts","sourceRoot":"","sources":["../../src/openapi/domain-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAwB7B;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,CAqB5E,CAAC"}

package/dist/openapi/domain-schemas.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.domainComponentNames = void 0;
+const generic_1 = require("@degenerate/generic");
+/**
+ * Stable OpenAPI component names for the centralized request/domain schemas in
+ * `@degenerate/generic`, keyed by the **raw** schema instance.
+ *
+ * Keyed by the raw instance (not a `.meta()` clone) on purpose: several rule
+ * schemas are recursive (`IShareRuleSchema` ↔ `IConditionSchema`, and
+ * `IShareRuleGroupSchema` via `z.lazy`), and those `z.lazy` thunks resolve to
+ * the raw generic instances. The generator must register the very instances
+ * the schema graph references, otherwise the recursive sub-schemas have no
+ * component id and Zod hoists them into a malformed shared-defs bucket. Every
+ * recursive schema below is also mounted as a `/validation` request body, so
+ * registering these names makes the whole graph resolve to clean `$ref`s.
+ */
+exports.domainComponentNames = [
+    [generic_1.ISAFETransactionAuthorityAddSchema, 'SAFETransactionAuthorityAdd'],
+    [generic_1.ISAFETransactionAuthorityUpdateSchema, 'SAFETransactionAuthorityUpdate'],
+    [generic_1.ISAFETransactionAuthorityDeleteSchema, 'SAFETransactionAuthorityDelete'],
+    [generic_1.ISAFETransactionEventAddSchema, 'SAFETransactionEventAdd'],
+    [generic_1.ISAFETransactionEventUpdateSchema, 'SAFETransactionEventUpdate'],
+    [generic_1.ISAFETransactionEventDeleteSchema, 'SAFETransactionEventDelete'],
+    [generic_1.ISAFETransactionFunctionAddSchema, 'SAFETransactionFunctionAdd'],
+    [generic_1.ISAFETransactionFunctionUpdateSchema, 'SAFETransactionFunctionUpdate'],
+    [generic_1.ISAFETransactionFunctionDeleteSchema, 'SAFETransactionFunctionDelete'],
+    [generic_1.ISAFETransactionRuleSetAddSchema, 'SAFETransactionRuleSetAdd'],
+    [generic_1.ISAFETransactionRuleSetUpdateSchema, 'SAFETransactionRuleSetUpdate'],
+    [generic_1.ISAFETransactionRuleSetDeleteSchema, 'SAFETransactionRuleSetDelete'],
+    [generic_1.ISAFETransactionShareDataAddSchema, 'SAFETransactionShareDataAdd'],
+    [generic_1.ISAFETransactionShareDataUpdateSchema, 'SAFETransactionShareDataUpdate'],
+    [generic_1.ISAFETransactionShareDataDeleteSchema, 'SAFETransactionShareDataDelete'],
+    [generic_1.IShareRuleSetSchema, 'ShareRuleSet'],
+    [generic_1.IShareRuleGroupSchema, 'ShareRuleGroup'],
+    [generic_1.IShareRuleAppliedSchema, 'ShareRuleApplied'],
+    [generic_1.IShareRuleSchema, 'ShareRule'],
+    [generic_1.IConditionSchema, 'Condition'],
+];

package/dist/openapi/index.d.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './response-schemas';
+export * from './domain-schemas';
+export * from './operations';
+export * from './build-openapi-document';
+//# sourceMappingURL=index.d.ts.map

package/dist/openapi/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/openapi/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,0BAA0B,CAAC"}

package/dist/openapi/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./response-schemas"), exports);
+__exportStar(require("./domain-schemas"), exports);
+__exportStar(require("./operations"), exports);
+__exportStar(require("./build-openapi-document"), exports);