@degenerate/endpoints 0.2.0 → 0.4.0

package/README.md

@@ -29,3 +29,21 @@ npm install @degenerate/endpoints
 ts-node ./packages/endpoints/src/examples/express-server/server.ts
 ```
 
+## OpenAPI
+
+The example server exposes a machine-readable description of its HTTP surface at:
+
+```
+GET /openapi.json
+```
+
+This route is public (no JWT) so codegen, Swagger UI, and contract-testing tools can fetch it freely. The document is an OpenAPI 3.0 spec generated by `buildOpenApiDocument()` from the same Zod schemas the routes validate against — request and response shapes never drift from what the handlers actually accept. To build the document outside the server (e.g. to write it to a file):
+
+```ts
+import { buildOpenApiDocument } from '@degenerate/endpoints';
+
+const spec = buildOpenApiDocument();
+```
+
+The operation surface is described by the `OperationDescriptor` arrays under `src/routes/**/**.openapi.ts`; a coverage test asserts the descriptors and the mounted Express routes stay in lockstep.
+

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":"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;AAWzD,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,CAqB3C;;AAKD,wBAAmC"}
+{"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

@@ -15,6 +15,7 @@ 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 cors_1 = require("../../cors");
+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
@@ -31,6 +32,13 @@ function createApp() {
     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);

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);

package/dist/openapi/operations.d.ts

@@ -0,0 +1,8 @@
+import type { OperationDescriptor } from './types';
+/**
+ * Every mounted SAFE HTTP operation, one descriptor each. This is the single
+ * feed for `buildOpenApiDocument` and the subject the coverage test reconciles
+ * against the live Express route table.
+ */
+export declare const operations: OperationDescriptor[];
+//# sourceMappingURL=operations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/openapi/operations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAQnD;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,mBAAmB,EAO3C,CAAC"}

package/dist/openapi/operations.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.operations = void 0;
+const v1_openapi_1 = require("../routes/authorities/v1.openapi");
+const v1_openapi_2 = require("../routes/events/v1.openapi");
+const v1_openapi_3 = require("../routes/functions/v1.openapi");
+const rule_set_openapi_1 = require("../routes/rules/v1/rule-set.openapi");
+const v1_openapi_4 = require("../routes/sharedata/v1.openapi");
+const validate_rules_openapi_1 = require("../routes/validation/rules/validate-rules.openapi");
+/**
+ * Every mounted SAFE HTTP operation, one descriptor each. This is the single
+ * feed for `buildOpenApiDocument` and the subject the coverage test reconciles
+ * against the live Express route table.
+ */
+exports.operations = [
+    ...v1_openapi_1.authorityOperations,
+    ...v1_openapi_2.eventOperations,
+    ...v1_openapi_3.functionOperations,
+    ...rule_set_openapi_1.ruleSetOperations,
+    ...v1_openapi_4.shareDataOperations,
+    ...validate_rules_openapi_1.validateRulesOperations,
+];

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

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+/**
+ * HTTP response envelopes for the SAFE endpoints surface. These describe the
+ * transport shape (`{ successful, … }`) the route handlers actually return —
+ * an HTTP concern specific to this API, deliberately kept out of
+ * `@degenerate/generic` (domain models). Payloads inside an envelope reuse
+ * generic domain schemas where one exists; otherwise the envelope is documented
+ * and the payload left loosely typed rather than fabricated.
+ *
+ * Define each schema once and reuse the instance so the OpenAPI generator
+ * dedupes it to a single `components.schemas` entry.
+ */
+/** Uniform error body emitted by the three error handlers at 400 / 403 / 404 / 500 / 501. */
+export declare const ErrorResponseSchema: z.ZodObject<{
+    successful: z.ZodLiteral<false>;
+    error: z.ZodString;
+}, z.core.$strip>;
+export type ErrorResponse = z.infer<typeof ErrorResponseSchema>;
+/** Bare success body: `{ successful: true }` with no additional payload. */
+export declare const SuccessResponseSchema: z.ZodObject<{
+    successful: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type SuccessResponse = z.infer<typeof SuccessResponseSchema>;
+/**
+ * Build a success envelope that carries extra fields alongside
+ * `successful: true`. Define the result as a module-level const in the group's
+ * descriptor file so the generator sees one stable instance per shape.
+ */
+export declare const successEnvelope: <Shape extends z.ZodRawShape>(payload: Shape) => z.ZodObject<{
+    successful: z.ZodLiteral<true>;
+} & Shape extends infer T ? { -readonly [P in keyof T]: T[P]; } : never, z.core.$strip>;
+//# sourceMappingURL=response-schemas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"response-schemas.d.ts","sourceRoot":"","sources":["../../src/openapi/response-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;GAUG;AAEH,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB;;;iBAEE,CAAC;AACnC,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB;;iBAEE,CAAC;AACrC,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,SAAS,CAAC,CAAC,WAAW,EAAE,SAAS,KAAK;;uFAClB,CAAC"}

package/dist/openapi/response-schemas.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.successEnvelope = exports.SuccessResponseSchema = exports.ErrorResponseSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * HTTP response envelopes for the SAFE endpoints surface. These describe the
+ * transport shape (`{ successful, … }`) the route handlers actually return —
+ * an HTTP concern specific to this API, deliberately kept out of
+ * `@degenerate/generic` (domain models). Payloads inside an envelope reuse
+ * generic domain schemas where one exists; otherwise the envelope is documented
+ * and the payload left loosely typed rather than fabricated.
+ *
+ * Define each schema once and reuse the instance so the OpenAPI generator
+ * dedupes it to a single `components.schemas` entry.
+ */
+/** Uniform error body emitted by the three error handlers at 400 / 403 / 404 / 500 / 501. */
+exports.ErrorResponseSchema = zod_1.z
+    .object({ successful: zod_1.z.literal(false), error: zod_1.z.string() })
+    .meta({ id: 'ErrorResponse' });
+/** Bare success body: `{ successful: true }` with no additional payload. */
+exports.SuccessResponseSchema = zod_1.z
+    .object({ successful: zod_1.z.literal(true) })
+    .meta({ id: 'SuccessResponse' });
+/**
+ * Build a success envelope that carries extra fields alongside
+ * `successful: true`. Define the result as a module-level const in the group's
+ * descriptor file so the generator sees one stable instance per shape.
+ */
+const successEnvelope = (payload) => zod_1.z.object({ successful: zod_1.z.literal(true), ...payload });
+exports.successEnvelope = successEnvelope;

package/dist/openapi/types.d.ts

@@ -0,0 +1,29 @@
+import type { z } from 'zod';
+import type { AuthorizationAudience } from '@degenerate/generic';
+/**
+ * One descriptor per mounted HTTP operation. This is the single place that
+ * records everything OpenAPI needs about an operation that Express does not
+ * expose introspectively: human summary, the JWT audience that gates it, and
+ * the Zod schemas bound to its request body and each response status.
+ *
+ * Descriptors live beside the route files they describe (one array per group,
+ * e.g. `routes/sharedata/v1.openapi.ts`) and are aggregated into a single
+ * `operations[]`. A coverage test reconciles `operations[]` against the live
+ * Express route table so the two cannot silently drift.
+ */
+export interface OperationDescriptor {
+    method: 'get' | 'post' | 'patch' | 'delete';
+    /** OpenAPI path template, e.g. `/share-data/v1/{sharedataid}`. */
+    path: string;
+    /** JWT audience that gates the operation, or `'public'` for no auth. */
+    security: AuthorizationAudience | 'public';
+    summary: string;
+    /** Request body schema; omit for operations that take no body. */
+    request?: z.ZodType;
+    /** Response schema per HTTP status — at minimum the success status. */
+    response: {
+        [status: number]: z.ZodType;
+    };
+    deprecated?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/openapi/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAChC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC5C,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,QAAQ,EAAE,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,OAAO,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IACpB,uEAAuE;IACvE,QAAQ,EAAE;QAAE,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,CAAA;KAAE,CAAC;IAC1C,UAAU,CAAC,EAAE,OAAO,CAAC;CACxB"}

package/dist/openapi/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/routes/authorities/v1.openapi.d.ts

@@ -0,0 +1,4 @@
+import type { OperationDescriptor } from '../../openapi/types';
+/** Operations under `/authorities` — all gated by the AUTHORITIES JWT audience. */
+export declare const authorityOperations: OperationDescriptor[];
+//# sourceMappingURL=v1.openapi.d.ts.map

package/dist/routes/authorities/v1.openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v1.openapi.d.ts","sourceRoot":"","sources":["../../../src/routes/authorities/v1.openapi.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAW/D,mFAAmF;AACnF,eAAO,MAAM,mBAAmB,EAAE,mBAAmB,EAyDpD,CAAC"}

package/dist/routes/authorities/v1.openapi.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authorityOperations = void 0;
+const zod_1 = require("zod");
+const generic_1 = require("@degenerate/generic");
+const response_schemas_1 = require("../../openapi/response-schemas");
+const AuthorityIdResponseSchema = (0, response_schemas_1.successEnvelope)({ authorityId: zod_1.z.string() }).meta({
+    id: 'AuthorityIdResponse',
+});
+/** Operations under `/authorities` — all gated by the AUTHORITIES JWT audience. */
+exports.authorityOperations = [
+    {
+        method: 'post',
+        path: '/authorities/v1',
+        security: generic_1.AuthorizationAudience.AUTHORITIES,
+        summary: 'Create an authority.',
+        request: generic_1.ISAFETransactionAuthorityAddSchema,
+        response: {
+            200: response_schemas_1.SuccessResponseSchema,
+            400: response_schemas_1.ErrorResponseSchema,
+            403: response_schemas_1.ErrorResponseSchema,
+        },
+    },
+    {
+        method: 'get',
+        path: '/authorities/v1',
+        security: generic_1.AuthorizationAudience.AUTHORITIES,
+        summary: 'List authorities.',
+        response: {
+            200: response_schemas_1.SuccessResponseSchema,
+            403: response_schemas_1.ErrorResponseSchema,
+        },
+    },
+    {
+        method: 'get',
+        path: '/authorities/v1/{authorityid}',
+        security: generic_1.AuthorizationAudience.AUTHORITIES,
+        summary: 'Get an authority by id.',
+        response: {
+            200: AuthorityIdResponseSchema,
+            403: response_schemas_1.ErrorResponseSchema,
+        },
+    },
+    {
+        method: 'patch',
+        path: '/authorities/v1/{authorityid}',
+        security: generic_1.AuthorizationAudience.AUTHORITIES,
+        summary: 'Update an authority by id.',
+        request: generic_1.ISAFETransactionAuthorityUpdateSchema,
+        response: {
+            200: AuthorityIdResponseSchema,
+            400: response_schemas_1.ErrorResponseSchema,
+            403: response_schemas_1.ErrorResponseSchema,
+        },
+    },
+    {
+        method: 'delete',
+        path: '/authorities/v1/{authorityid}',
+        security: generic_1.AuthorizationAudience.AUTHORITIES,
+        summary: 'Delete an authority by id.',
+        request: generic_1.ISAFETransactionAuthorityDeleteSchema,
+        response: {
+            200: AuthorityIdResponseSchema,
+            400: response_schemas_1.ErrorResponseSchema,
+            403: response_schemas_1.ErrorResponseSchema,
+        },
+    },
+];

package/dist/routes/events/v1.openapi.d.ts

@@ -0,0 +1,4 @@
+import type { OperationDescriptor } from '../../openapi/types';
+/** Operations under `/events` — all gated by the EVENTS JWT audience. */
+export declare const eventOperations: OperationDescriptor[];
+//# sourceMappingURL=v1.openapi.d.ts.map

package/dist/routes/events/v1.openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v1.openapi.d.ts","sourceRoot":"","sources":["../../../src/routes/events/v1.openapi.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG/D,yEAAyE;AACzE,eAAO,MAAM,eAAe,EAAE,mBAAmB,EA+ChD,CAAC"}