@bajustone/fortress 1.0.0-rc.1

package/dist/plugins/openapi.js

@@ -0,0 +1,1158 @@
+// src/core/schema-builder.ts
+import { fromJSONSchema } from "@bajustone/fetcher/openapi";
+import { date as fDate, datetime as fDatetime, email as fEmail, time as fTime, url as fUrl, uuid as fUuid } from "@bajustone/fetcher/schema";
+function collectRefNames(schema, acc) {
+  if (!schema || typeof schema !== "object")
+    return acc;
+  if (typeof schema.$ref === "string") {
+    const i = schema.$ref.lastIndexOf("/");
+    acc.add(i >= 0 ? schema.$ref.slice(i + 1) : schema.$ref);
+  }
+  if (schema.properties) {
+    for (const key of Object.keys(schema.properties))
+      collectRefNames(schema.properties[key], acc);
+  }
+  collectRefNames(schema.items, acc);
+  for (const key of ["oneOf", "anyOf", "allOf"]) {
+    const variants = schema[key];
+    if (variants) {
+      for (const variant of variants)
+        collectRefNames(variant, acc);
+    }
+  }
+  if (schema.additionalProperties && typeof schema.additionalProperties === "object")
+    collectRefNames(schema.additionalProperties, acc);
+  return acc;
+}
+var refDefinitionContexts = /* @__PURE__ */ new WeakMap();
+function refName(refPath) {
+  const i = refPath.lastIndexOf("/");
+  return i >= 0 ? refPath.slice(i + 1) : refPath;
+}
+var COMPONENT_NAME_RE = /^[\w.-]+$/;
+function assertComponentName(name) {
+  if (!COMPONENT_NAME_RE.test(name))
+    throw new Error(`Invalid OpenAPI component name '${name}'`);
+}
+function resolveRefDefs(schema) {
+  if (collectRefNames(schema, /* @__PURE__ */ new Set()).size === 0)
+    return void 0;
+  const defs = /* @__PURE__ */ Object.create(null);
+  const unresolved = /* @__PURE__ */ new Set();
+  const hasOwn = (value, key) => Object.hasOwn(value, key);
+  const visit = (node, inherited) => {
+    if (!node || typeof node !== "object")
+      return;
+    const context = refDefinitionContexts.get(node) ?? inherited;
+    if (typeof node.$ref === "string") {
+      const name = refName(node.$ref);
+      const component = context && hasOwn(context, name) ? context[name] : void 0;
+      if (component) {
+        if (hasOwn(defs, name) && !unresolved.has(name) && defs[name] !== component) {
+          throw new Error(`Conflicting component definitions for $ref '${name}'`);
+        }
+        const firstResolution = !hasOwn(defs, name) || unresolved.delete(name);
+        defs[name] = component;
+        if (firstResolution)
+          visit(component, context);
+      } else if (!hasOwn(defs, name)) {
+        defs[name] = {};
+        unresolved.add(name);
+      }
+    }
+    if (node.properties) {
+      for (const child of Object.values(node.properties))
+        visit(child, context);
+    }
+    visit(node.items, context);
+    for (const key of ["oneOf", "anyOf", "allOf"]) {
+      for (const child of node[key] ?? [])
+        visit(child, context);
+    }
+    if (node.additionalProperties && typeof node.additionalProperties === "object")
+      visit(node.additionalProperties, context);
+  };
+  visit(schema);
+  return defs;
+}
+function createStandardProps(schema) {
+  let validateFn;
+  return {
+    version: 1,
+    vendor: "fortress",
+    validate(value) {
+      if (!validateFn) {
+        const defs = resolveRefDefs(schema);
+        validateFn = fromJSONSchema(schema, defs)["~standard"].validate;
+      }
+      return validateFn(value);
+    }
+  };
+}
+function createExactOneOfProps(schemas) {
+  const validate = (value) => {
+    const results = schemas.map((schema) => schema["~standard"].validate(value));
+    if (results.some((result) => result instanceof Promise)) {
+      return Promise.all(results).then((resolved) => exactOneResult(resolved));
+    }
+    return exactOneResult(results);
+  };
+  return {
+    version: 1,
+    vendor: "fortress",
+    validate
+  };
+}
+function exactOneResult(results) {
+  const successes = results.filter((result) => !result.issues);
+  if (successes.length === 1)
+    return { value: successes[0].value };
+  return {
+    issues: [{
+      message: successes.length === 0 ? "Value must match exactly one oneOf variant" : "Value must match exactly one oneOf variant; multiple variants matched"
+    }]
+  };
+}
+function toFortressSchema(schema, refDefinitions, standardProps) {
+  if (refDefinitions)
+    refDefinitionContexts.set(schema, refDefinitions);
+  return Object.assign(schema, {
+    "~standard": standardProps ?? createStandardProps(schema)
+  });
+}
+function str(opts) {
+  const o = typeof opts === "string" ? { description: opts } : opts ?? {};
+  const s = { type: "string" };
+  if (o.description)
+    s.description = o.description;
+  if (o.min !== void 0)
+    s.minLength = o.min;
+  if (o.max !== void 0)
+    s.maxLength = o.max;
+  if (o.pattern !== void 0)
+    s.pattern = o.pattern;
+  if (o.format !== void 0)
+    s.format = o.format;
+  return toFortressSchema(s);
+}
+function int(opts) {
+  const o = typeof opts === "string" ? { description: opts } : opts ?? {};
+  const s = { type: "integer" };
+  if (o.description)
+    s.description = o.description;
+  if (o.min !== void 0)
+    s.minimum = o.min;
+  if (o.max !== void 0)
+    s.maximum = o.max;
+  return toFortressSchema(s);
+}
+function id(description) {
+  const s = { type: "string", minLength: 1 };
+  if (description)
+    s.description = description;
+  return toFortressSchema(s);
+}
+function bool(description) {
+  const s = { type: "boolean" };
+  if (description)
+    s.description = description;
+  return toFortressSchema(s);
+}
+function arr(items, description) {
+  const s = { type: "array", items };
+  if (description)
+    s.description = description;
+  return toFortressSchema(s);
+}
+function obj(properties, ...required) {
+  const s = { type: "object", properties };
+  if (required.length > 0)
+    s.required = required;
+  return toFortressSchema(s);
+}
+function nullable(schema) {
+  if (typeof schema.$ref === "string")
+    return toFortressSchema({ oneOf: [schema, { type: "null" }] });
+  const s = { ...schema, nullable: true };
+  return toFortressSchema(s, refDefinitionContexts.get(schema));
+}
+function oneOf(...schemas) {
+  const schema = { oneOf: schemas };
+  return toFortressSchema(
+    schema,
+    void 0,
+    createExactOneOfProps(schemas)
+  );
+}
+function defineComponents(components) {
+  for (const name of Object.keys(components))
+    assertComponentName(name);
+  const definitions = Object.assign(
+    /* @__PURE__ */ Object.create(null),
+    components
+  );
+  return {
+    components,
+    ref: (name) => {
+      assertComponentName(name);
+      return toFortressSchema(
+        { $ref: `#/components/schemas/${String(name)}` },
+        definitions
+      );
+    }
+  };
+}
+function enums(...values) {
+  return toFortressSchema({ enum: values });
+}
+function strFormat(format, description) {
+  const s = { type: "string", format };
+  if (description)
+    s.description = description;
+  return toFortressSchema(s);
+}
+function nullType() {
+  return toFortressSchema({ type: "null" });
+}
+function record(description) {
+  const s = { type: "object", additionalProperties: true };
+  if (description)
+    s.description = description;
+  return toFortressSchema(s);
+}
+function recordOf(valueSchema, description) {
+  const s = { type: "object", additionalProperties: valueSchema };
+  if (description)
+    s.description = description;
+  return toFortressSchema(s);
+}
+function makeFormatBuilder(factory) {
+  const f = factory();
+  return (description) => {
+    const s = { type: "string" };
+    if (f.format)
+      s.format = f.format;
+    if (f.pattern)
+      s.pattern = f.pattern;
+    if (description)
+      s.description = description;
+    return toFortressSchema(s);
+  };
+}
+var email = makeFormatBuilder(fEmail);
+var uuid = makeFormatBuilder(fUuid);
+var url = makeFormatBuilder(fUrl);
+var datetime = makeFormatBuilder(fDatetime);
+var date = makeFormatBuilder(fDate);
+var time = makeFormatBuilder(fTime);
+function isStandardSchema(value) {
+  return typeof value === "object" && value !== null && "~standard" in value && typeof value["~standard"]?.validate === "function";
+}
+function isFortressSchema(value) {
+  return isStandardSchema(value) && value["~standard"].vendor === "fortress" && ("type" in value || "$ref" in value || "oneOf" in value || "anyOf" in value);
+}
+var JSON_SCHEMA_TYPES = /* @__PURE__ */ new Set(["string", "number", "integer", "boolean", "object", "array", "null"]);
+function hasJsonSchemaShape(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const v = value;
+  if ("$ref" in v || "oneOf" in v || "anyOf" in v || "allOf" in v)
+    return true;
+  if (typeof v.type === "string" && JSON_SCHEMA_TYPES.has(v.type))
+    return true;
+  if (Array.isArray(v.type) && v.type.every((t) => typeof t === "string" && JSON_SCHEMA_TYPES.has(t)))
+    return true;
+  return false;
+}
+function extractJsonSchema(schema) {
+  if (isFortressSchema(schema)) {
+    return schema;
+  }
+  if (isStandardSchema(schema)) {
+    const std = schema["~standard"];
+    if (std?.jsonSchema?.input) {
+      return std.jsonSchema.input({ target: "draft-2020-12" });
+    }
+    if (hasJsonSchemaShape(schema)) {
+      return schema;
+    }
+  }
+  return {};
+}
+var ErrorEnvelope = obj({
+  code: str("Machine-readable error code"),
+  message: str("Human-readable error message"),
+  statusCode: int("HTTP status code"),
+  details: toFortressSchema({ description: "Optional structured error details" })
+}, "code", "message", "statusCode");
+var EndpointBuilder = class {
+  _method;
+  _path;
+  _handler = "";
+  _summary = "";
+  _description;
+  _tags = [];
+  _security = [];
+  _deprecated = false;
+  _permission;
+  _body;
+  _query;
+  _params;
+  _responses = {};
+  constructor(method, path) {
+    this._method = method;
+    this._path = path;
+  }
+  summary(s) {
+    this._summary = s;
+    return this;
+  }
+  description(s) {
+    this._description = s;
+    return this;
+  }
+  tags(...t) {
+    this._tags.push(...t);
+    return this;
+  }
+  security(...s) {
+    this._security.push(...s);
+    return this;
+  }
+  deprecated() {
+    this._deprecated = true;
+    return this;
+  }
+  permission(resource, action) {
+    this._permission = { resource, action };
+    return this;
+  }
+  body(schema) {
+    this._body = schema;
+    return this;
+  }
+  query(schema) {
+    this._query = schema;
+    return this;
+  }
+  params(schema) {
+    this._params = schema;
+    return this;
+  }
+  response(status, description, schema) {
+    const stored = { description };
+    if (schema !== void 0) {
+      stored.schema = isStandardSchema(schema) ? extractJsonSchema(schema) : schema;
+    }
+    this._responses[status] = stored;
+    return this;
+  }
+  /**
+   * Declare an error response that returns the canonical {@link ErrorEnvelope}
+   * body. Shorthand for `.response(status, description, ErrorEnvelope)`.
+   *
+   * Aligns host endpoint error responses with what Fortress's own routes
+   * emit, so a single client-side error parser works everywhere.
+   *
+   * ```ts
+   * endpoint('GET', '/schools/:id')
+   *   .summary('Get a school')
+   *   .params(obj({ id: str() }, 'id'))
+   *   .response(200, 'OK', SchoolEnvelope)
+   *   .errorResponse(404, 'School not found')
+   *   .errorResponse(403, 'Forbidden')
+   *   .build();
+   * ```
+   */
+  errorResponse(status, description) {
+    return this.response(status, description, ErrorEnvelope);
+  }
+  handler(name) {
+    this._handler = name;
+    return this;
+  }
+  build() {
+    const def = {
+      method: this._method,
+      path: this._path,
+      handler: this._handler
+    };
+    if (this._summary || this._tags.length > 0 || this._security.length > 0 || this._description || this._deprecated || this._permission) {
+      def.meta = {
+        summary: this._summary,
+        ...this._description && { description: this._description },
+        ...this._tags.length > 0 && { tags: this._tags },
+        ...this._security.length > 0 && { security: this._security },
+        ...this._deprecated && { deprecated: true },
+        ...this._permission && { permission: this._permission }
+      };
+    }
+    if (this._body || this._query || this._params) {
+      def.input = {};
+      if (this._body) {
+        def.input.body = extractJsonSchema(this._body);
+        if (isStandardSchema(this._body))
+          def.input.bodySchema = this._body;
+      }
+      if (this._query) {
+        def.input.query = extractJsonSchema(this._query);
+        if (isStandardSchema(this._query))
+          def.input.querySchema = this._query;
+      }
+      if (this._params) {
+        def.input.params = extractJsonSchema(this._params);
+        if (isStandardSchema(this._params))
+          def.input.paramsSchema = this._params;
+      }
+    }
+    if (Object.keys(this._responses).length > 0) {
+      def.responses = this._responses;
+    }
+    return def;
+  }
+};
+function endpoint(method, path) {
+  return new EndpointBuilder(method, path);
+}
+
+// src/core/auth/auth-endpoints.ts
+var User = obj(
+  {
+    id: id("User ID"),
+    email: strFormat("email", "User email"),
+    name: str("Display name"),
+    isActive: bool("Account active status"),
+    emailVerified: bool("Email verification status"),
+    createdAt: strFormat("date-time", "Creation timestamp"),
+    updatedAt: strFormat("date-time", "Last update timestamp")
+  },
+  "id",
+  "email",
+  "name",
+  "isActive",
+  "createdAt",
+  "updatedAt"
+);
+var AuthChallenge = obj(
+  {
+    reason: enums("two-factor", "webauthn", "email-verification", "magic-link"),
+    continuationToken: str("Single-use post-auth continuation token")
+  },
+  "reason",
+  "continuationToken"
+);
+var AuthResult = oneOf(
+  obj(
+    {
+      status: enums("success"),
+      user: User,
+      method: enums("password", "refresh", "two-factor", "webauthn", "magic-link", "impersonation"),
+      accessToken: str("JWT access token"),
+      refreshToken: str("Refresh token for rotation"),
+      pluginData: record()
+    },
+    "status",
+    "user",
+    "method",
+    "accessToken",
+    "refreshToken"
+  ),
+  obj(
+    {
+      status: enums("pending"),
+      user: User,
+      pending: AuthChallenge,
+      pluginData: record()
+    },
+    "status",
+    "user",
+    "pending"
+  ),
+  obj(
+    {
+      status: enums("impersonation"),
+      user: User,
+      accessToken: str("JWT access token"),
+      refreshToken: nullType(),
+      pluginData: record()
+    },
+    "status",
+    "user",
+    "accessToken",
+    "refreshToken"
+  )
+);
+var AuthTokenPair = obj(
+  {
+    accessToken: str("JWT access token"),
+    refreshToken: str("New refresh token")
+  },
+  "accessToken",
+  "refreshToken"
+);
+var SessionInfo = obj(
+  {
+    id: id("Token ID"),
+    ipAddress: nullable(str("Client IP address")),
+    userAgent: nullable(str("Client user agent")),
+    deviceName: nullable(str("Device name")),
+    createdAt: strFormat("date-time", "Session creation time"),
+    lastActiveAt: nullable(strFormat("date-time", "Last activity time"))
+  },
+  "id",
+  "createdAt"
+);
+var CreateUserInput = obj(
+  {
+    email: email("User email"),
+    // enforced format (ReDoS-safe pattern), not annotation-only
+    name: str("Display name"),
+    password: str("User password"),
+    isActive: bool("Set active status (default true)")
+  },
+  "email",
+  "name"
+);
+var ErrorResponse = obj(
+  {
+    code: str("Error code (e.g. UNAUTHORIZED)"),
+    message: str("Human-readable message"),
+    statusCode: int("HTTP status code")
+  },
+  "code",
+  "message",
+  "statusCode"
+);
+var LoginIdentifier = obj(
+  {
+    id: id("Identifier ID"),
+    userId: id("User ID"),
+    type: enums("email", "phone", "username"),
+    value: str("Identifier value")
+  },
+  "id",
+  "userId",
+  "type",
+  "value"
+);
+var authComponents = defineComponents({
+  User,
+  AuthChallenge,
+  AuthResult,
+  AuthTokenPair,
+  SessionInfo,
+  CreateUserInput,
+  ErrorResponse,
+  LoginIdentifier
+});
+var authComponentSchemas = authComponents.components;
+var authRef = authComponents.ref;
+var authEndpoints = {
+  login: endpoint("POST", "/auth/login").summary("Login with credentials").tags("Auth").security("none").body(obj(
+    {
+      identifier: str("Email, username, or phone"),
+      password: str("User password"),
+      trustedDeviceToken: str("Opaque trusted-device token previously returned after two-factor verification")
+    },
+    "identifier",
+    "password"
+  )).response(200, "Login successful", authRef("AuthResult")).response(401, "Invalid credentials", authRef("ErrorResponse")).handler("login").build(),
+  verifyTwoFactor: endpoint("POST", "/auth/2fa/verify").summary("Complete a pending two-factor challenge").tags("Auth", "Two-Factor").security("none").body(obj(
+    {
+      continuationToken: str("Single-use auth continuation token"),
+      code: str("TOTP or backup code"),
+      rememberDevice: bool("Issue an opaque trusted-device token after successful verification")
+    },
+    "continuationToken",
+    "code"
+  )).response(200, "Authentication result", authRef("AuthResult")).response(400, "Two-factor plugin unavailable", authRef("ErrorResponse")).response(401, "Invalid continuation or verification code", authRef("ErrorResponse")).handler("verifyTwoFactor").build(),
+  verifyMagicLink: endpoint("POST", "/auth/magic-link/verify").summary("Verify a magic-link token").tags("Auth", "Magic Link").security("none").body(obj({ token: str("Raw magic-link token") }, "token")).response(200, "Authentication result", authRef("AuthResult")).response(400, "Magic-link plugin unavailable", authRef("ErrorResponse")).response(404, "Invalid or expired magic link", authRef("ErrorResponse")).handler("verifyMagicLink").build(),
+  createUser: endpoint("POST", "/auth/register").summary("Create a new user").tags("Auth").security("none").body(CreateUserInput).response(201, "User created", authRef("User")).response(409, "Email already exists", authRef("ErrorResponse")).handler("createUser").build(),
+  refresh: endpoint("POST", "/auth/refresh").summary("Refresh access token").tags("Auth").security("none").body(obj({ refreshToken: str("Current refresh token") }, "refreshToken")).response(200, "Tokens refreshed", authRef("AuthTokenPair")).response(401, "Invalid or expired refresh token", authRef("ErrorResponse")).handler("refresh").build(),
+  logout: endpoint("POST", "/auth/logout").summary("Logout and revoke refresh token").tags("Auth").security("none").body(obj({ refreshToken: str("Refresh token to revoke") }, "refreshToken")).response(200, "Logged out", obj({ ok: bool() }, "ok")).handler("logout").build(),
+  me: endpoint("GET", "/auth/me").summary("Get current user profile").tags("Auth").security("bearer").response(200, "Current user", authRef("User")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("me").build(),
+  listSessions: endpoint("GET", "/auth/sessions").summary("List active sessions").tags("Auth").security("bearer").response(200, "Active sessions", arr(authRef("SessionInfo"))).response(401, "Not authenticated", authRef("ErrorResponse")).handler("listSessions").build(),
+  revokeSession: endpoint("DELETE", "/auth/sessions/:id").summary("Revoke a specific session").tags("Auth").security("bearer").params(obj({ id: id("Session/token ID") }, "id")).response(200, "Session revoked", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("revokeSession").build(),
+  revokeAllOtherSessions: endpoint("DELETE", "/auth/sessions").summary("Revoke all other sessions").description("Revokes all active sessions except the current one. Requires the current token ID.").tags("Auth").security("bearer").body(obj({ currentTokenId: id("Current token ID to keep") }, "currentTokenId")).response(200, "Other sessions revoked", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("revokeAllOtherSessions").build(),
+  addLoginIdentifier: endpoint("POST", "/auth/identifiers").summary("Add a login identifier").tags("Auth").security("bearer").body(obj(
+    {
+      type: enums("email", "phone", "username"),
+      value: str("Identifier value")
+    },
+    "type",
+    "value"
+  )).response(200, "Identifier added", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("addLoginIdentifier").build(),
+  removeLoginIdentifier: endpoint("DELETE", "/auth/identifiers").summary("Remove a login identifier").tags("Auth").security("bearer").body(obj(
+    {
+      type: enums("email", "phone", "username"),
+      value: str("Identifier value")
+    },
+    "type",
+    "value"
+  )).response(200, "Identifier removed", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("removeLoginIdentifier").build(),
+  getLoginIdentifiers: endpoint("GET", "/auth/identifiers").summary("List login identifiers").tags("Auth").security("bearer").response(200, "Login identifiers", arr(authRef("LoginIdentifier"))).response(401, "Not authenticated", authRef("ErrorResponse")).handler("getLoginIdentifiers").build(),
+  impersonate: endpoint("POST", "/auth/impersonate").summary("Impersonate a user").description("Issue a short-lived, non-renewable token to act as another user. Requires fortress:impersonate permission.").tags("Auth").security("bearer").permission("fortress", "impersonate").body(obj(
+    {
+      targetUserId: id("User to impersonate"),
+      reason: str("Reason for impersonation"),
+      expirySeconds: int("Token expiry in seconds (default 3600)")
+    },
+    "targetUserId"
+  )).response(200, "Impersonation token issued", authRef("AuthResult")).response(401, "Not authenticated", authRef("ErrorResponse")).response(404, "Target user not found", authRef("ErrorResponse")).handler("impersonate").build()
+};
+
+// src/core/iam/iam-endpoints.ts
+var Role = obj(
+  {
+    id: id("Role ID"),
+    name: str("Role name"),
+    description: nullable(str("Role description")),
+    isSystem: bool("Whether this is a system role")
+  },
+  "id",
+  "name"
+);
+var Group = obj(
+  {
+    id: id("Group ID"),
+    name: str("Group name"),
+    description: nullable(str("Group description"))
+  },
+  "id",
+  "name"
+);
+var Permission = obj(
+  {
+    id: id("Permission ID"),
+    resource: str("Resource name"),
+    action: str("Action name"),
+    effect: enums("ALLOW", "DENY"),
+    conditions: arr(obj({
+      field: str("Condition field"),
+      operator: enums("eq", "neq", "in", "startsWith"),
+      value: str("Condition value")
+    }), "Permission conditions"),
+    description: nullable(str("Permission description"))
+  },
+  "id",
+  "resource",
+  "action",
+  "effect"
+);
+var PermissionInput = obj(
+  {
+    resource: str("Resource name"),
+    action: str("Action name"),
+    effect: enums("ALLOW", "DENY"),
+    conditions: arr(obj({
+      field: str("Condition field"),
+      operator: enums("eq", "neq", "in", "startsWith"),
+      value: str("Condition value")
+    }))
+  },
+  "resource",
+  "action"
+);
+var ServiceAccount = obj(
+  {
+    id: id("Service account ID"),
+    name: str("Machine identifier \u2014 immutable after creation"),
+    displayName: nullable(str("Human-readable label")),
+    description: nullable(str("Free-form description")),
+    isActive: bool("Whether the account can authenticate and resolve permissions"),
+    createdAt: str("ISO 8601 creation timestamp"),
+    updatedAt: str("ISO 8601 update timestamp")
+  },
+  "id",
+  "name",
+  "isActive"
+);
+var iamComponents = defineComponents({
+  Role,
+  Group,
+  Permission,
+  PermissionInput,
+  ServiceAccount
+});
+var iamComponentSchemas = iamComponents.components;
+var iamRef = iamComponents.ref;
+var iamEndpoints = {
+  // ── Resources ──
+  getResources: endpoint("GET", "/iam/resources").summary("List all available resources").tags("IAM", "Resources").security("bearer").permission("fortress", "viewResources").response(200, "Available resources with their actions", obj({
+    resources: recordOf(obj({
+      actions: arr(str("Action name"), "Available actions"),
+      description: str("Resource description")
+    }), "Map of resource name to definition")
+  }, "resources")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("getResources").build(),
+  // ── Roles ──
+  getRoles: endpoint("GET", "/iam/roles").summary("List all roles").tags("IAM", "Roles").security("bearer").permission("fortress", "viewRoles").response(200, "All roles", arr(iamRef("Role"))).response(401, "Not authenticated", authRef("ErrorResponse")).handler("getRoles").build(),
+  createRole: endpoint("POST", "/iam/roles").summary("Create a role").tags("IAM", "Roles").security("bearer").permission("fortress", "createRole").body(obj(
+    {
+      name: str("Role name"),
+      permissions: arr(iamRef("PermissionInput"), "Permissions to assign"),
+      description: str("Role description")
+    },
+    "name",
+    "permissions"
+  )).response(201, "Role created", iamRef("Role")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("createRole").build(),
+  deleteRole: endpoint("DELETE", "/iam/roles/:id").summary("Delete a role").tags("IAM", "Roles").security("bearer").permission("fortress", "deleteRole").params(obj({ id: id("Role ID") }, "id")).response(200, "Role deleted", obj({ ok: bool() }, "ok")).response(400, "Cannot delete system role", authRef("ErrorResponse")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("deleteRole").build(),
+  // ── Role Bindings ──
+  bindRoleToUser: endpoint("POST", "/iam/roles/:id/bind/user").summary("Bind role to a user").tags("IAM", "Roles").security("bearer").permission("fortress", "bindRole").params(obj({ id: id("Role ID") }, "id")).body(obj(
+    { userId: id("User ID"), tenantId: str("Tenant ID (optional)") },
+    "userId"
+  )).response(200, "Role bound to user", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("bindRoleToUser").build(),
+  bindRoleToGroup: endpoint("POST", "/iam/roles/:id/bind/group").summary("Bind role to a group").tags("IAM", "Roles").security("bearer").permission("fortress", "bindRole").params(obj({ id: id("Role ID") }, "id")).body(obj(
+    { groupId: id("Group ID"), tenantId: str("Tenant ID (optional)") },
+    "groupId"
+  )).response(200, "Role bound to group", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("bindRoleToGroup").build(),
+  unbindRole: endpoint("DELETE", "/iam/roles/:id/bind").summary("Unbind a role").tags("IAM", "Roles").security("bearer").permission("fortress", "unbindRole").params(obj({ id: id("Role ID") }, "id")).body(obj(
+    {
+      subjectType: enums("USER", "GROUP", "SERVICE_ACCOUNT"),
+      subjectId: id("Subject ID"),
+      tenantId: str("Tenant ID (optional)")
+    },
+    "subjectType",
+    "subjectId"
+  )).response(200, "Role unbound", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("unbindRole").build(),
+  // ── Groups ──
+  createGroup: endpoint("POST", "/iam/groups").summary("Create a group").tags("IAM", "Groups").security("bearer").permission("fortress", "createGroup").body(obj(
+    { name: str("Group name"), description: str("Group description") },
+    "name"
+  )).response(201, "Group created", iamRef("Group")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("createGroup").build(),
+  addUserToGroup: endpoint("POST", "/iam/groups/:id/users").summary("Add user to group").tags("IAM", "Groups").security("bearer").permission("fortress", "manageGroup").params(obj({ id: id("Group ID") }, "id")).body(obj({ userId: id("User ID") }, "userId")).response(200, "User added to group", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("addUserToGroup").build(),
+  removeUserFromGroup: endpoint("DELETE", "/iam/groups/:id/users/:userId").summary("Remove user from group").tags("IAM", "Groups").security("bearer").permission("fortress", "manageGroup").params(obj({ id: id("Group ID"), userId: id("User ID") }, "id", "userId")).response(200, "User removed from group", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("removeUserFromGroup").build(),
+  // ── Permissions ──
+  getUserPermissions: endpoint("GET", "/iam/users/:id/permissions").summary("Get user permissions").tags("IAM", "Permissions").security("bearer").permission("fortress", "viewPermissions").params(obj({ id: id("User ID") }, "id")).query(obj({ tenantId: str("Tenant ID (optional)") })).response(200, "User permissions", arr(iamRef("Permission"))).response(401, "Not authenticated", authRef("ErrorResponse")).handler("getUserPermissions").build(),
+  checkPermission: endpoint("POST", "/iam/check").summary("Check if user has permission").tags("IAM", "Permissions").security("bearer").permission("fortress", "viewPermissions").body(obj(
+    {
+      userId: id("User ID"),
+      resource: str("Resource name"),
+      action: str("Action name"),
+      context: record("Permission context")
+    },
+    "userId",
+    "resource",
+    "action"
+  )).response(200, "Permission check result", obj({ allowed: bool("Whether permission is granted") }, "allowed")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("checkPermission").build(),
+  bindPermissionToUser: endpoint("POST", "/iam/permissions/bind/user").summary("Bind permission directly to a user").tags("IAM", "Permissions").security("bearer").permission("fortress", "managePermissions").body(obj(
+    {
+      userId: id("User ID"),
+      permission: iamRef("PermissionInput"),
+      tenantId: str("Tenant ID (optional)")
+    },
+    "userId",
+    "permission"
+  )).response(200, "Permission bound", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("bindPermissionToUser").build(),
+  bindPermissionToGroup: endpoint("POST", "/iam/permissions/bind/group").summary("Bind permission directly to a group").tags("IAM", "Permissions").security("bearer").permission("fortress", "managePermissions").body(obj(
+    {
+      groupId: id("Group ID"),
+      permission: iamRef("PermissionInput"),
+      tenantId: str("Tenant ID (optional)")
+    },
+    "groupId",
+    "permission"
+  )).response(200, "Permission bound", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("bindPermissionToGroup").build(),
+  unbindPermissionFromUser: endpoint("DELETE", "/iam/permissions/bind/user").summary("Unbind permission from a user").tags("IAM", "Permissions").security("bearer").permission("fortress", "managePermissions").body(obj(
+    {
+      userId: id("User ID"),
+      permissionId: id("Permission ID"),
+      tenantId: str("Tenant ID (optional)")
+    },
+    "userId",
+    "permissionId"
+  )).response(200, "Permission unbound", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("unbindPermissionFromUser").build(),
+  unbindPermissionFromGroup: endpoint("DELETE", "/iam/permissions/bind/group").summary("Unbind permission from a group").tags("IAM", "Permissions").security("bearer").permission("fortress", "managePermissions").body(obj(
+    {
+      groupId: id("Group ID"),
+      permissionId: id("Permission ID"),
+      tenantId: str("Tenant ID (optional)")
+    },
+    "groupId",
+    "permissionId"
+  )).response(200, "Permission unbound", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("unbindPermissionFromGroup").build(),
+  // ── Service Accounts ──
+  createServiceAccount: endpoint("POST", "/iam/service-accounts").summary("Create a service account").description("Create a non-human IAM principal. Service accounts hold roles and direct permissions just like users, but have no sessions, passwords, or group memberships. The `name` is immutable after creation.").tags("IAM", "Service Accounts").security("bearer").permission("fortress", "createServiceAccount").body(obj(
+    {
+      name: str("Machine identifier (immutable)"),
+      displayName: str("Human-readable label"),
+      description: str("Free-form description")
+    },
+    "name"
+  )).response(201, "Service account created", iamRef("ServiceAccount")).response(400, "Bad request", authRef("ErrorResponse")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("createServiceAccount").build(),
+  listServiceAccounts: endpoint("GET", "/iam/service-accounts").summary("List service accounts").tags("IAM", "Service Accounts").security("bearer").permission("fortress", "viewServiceAccounts").query(obj({
+    limit: int("Page size (default 50)"),
+    offset: int("Offset from the start of the list")
+  })).response(200, "Service accounts", obj({
+    serviceAccounts: arr(iamRef("ServiceAccount")),
+    total: int("Total service accounts")
+  }, "serviceAccounts", "total")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("listServiceAccounts").build(),
+  getServiceAccount: endpoint("GET", "/iam/service-accounts/:id").summary("Get a service account by ID").tags("IAM", "Service Accounts").security("bearer").permission("fortress", "viewServiceAccounts").params(obj({ id: id("Service account ID") }, "id")).response(200, "Service account", iamRef("ServiceAccount")).response(401, "Not authenticated", authRef("ErrorResponse")).response(404, "Not found", authRef("ErrorResponse")).handler("getServiceAccount").build(),
+  updateServiceAccount: endpoint("PATCH", "/iam/service-accounts/:id").summary("Update a service account").description("Update displayName, description, or isActive. The `name` field is immutable \u2014 to rename, delete and recreate.").tags("IAM", "Service Accounts").security("bearer").permission("fortress", "manageServiceAccount").params(obj({ id: id("Service account ID") }, "id")).body(obj({
+    displayName: nullable(str("New human-readable label")),
+    description: nullable(str("New description")),
+    isActive: bool("Whether the account is active")
+  })).response(200, "Service account updated", iamRef("ServiceAccount")).response(401, "Not authenticated", authRef("ErrorResponse")).response(404, "Not found", authRef("ErrorResponse")).handler("updateServiceAccount").build(),
+  deleteServiceAccount: endpoint("DELETE", "/iam/service-accounts/:id").summary("Delete a service account").description("Hard-deletes the service account and cascades to role bindings, direct permission bindings, and (via plugin observer) api keys owned by the account.").tags("IAM", "Service Accounts").security("bearer").permission("fortress", "manageServiceAccount").params(obj({ id: id("Service account ID") }, "id")).response(200, "Service account deleted", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).response(404, "Not found", authRef("ErrorResponse")).handler("deleteServiceAccount").build(),
+  getServiceAccountPermissions: endpoint("GET", "/iam/service-accounts/:id/permissions").summary("Get effective permissions for a service account").tags("IAM", "Service Accounts", "Permissions").security("bearer").permission("fortress", "viewPermissions").params(obj({ id: id("Service account ID") }, "id")).query(obj({ tenantId: str("Tenant ID (optional)") })).response(200, "Service account permissions", arr(iamRef("Permission"))).response(401, "Not authenticated", authRef("ErrorResponse")).handler("getServiceAccountPermissions").build(),
+  bindRoleToServiceAccount: endpoint("POST", "/iam/roles/:id/bind/service-account").summary("Bind role to a service account").tags("IAM", "Roles", "Service Accounts").security("bearer").permission("fortress", "bindRole").params(obj({ id: id("Role ID") }, "id")).body(obj(
+    { serviceAccountId: id("Service account ID"), tenantId: str("Tenant ID (optional)") },
+    "serviceAccountId"
+  )).response(200, "Role bound to service account", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("bindRoleToServiceAccount").build(),
+  unbindRoleFromServiceAccount: endpoint("DELETE", "/iam/roles/:id/bind/service-account").summary("Unbind role from a service account").tags("IAM", "Roles", "Service Accounts").security("bearer").permission("fortress", "unbindRole").params(obj({ id: id("Role ID") }, "id")).body(obj(
+    { serviceAccountId: id("Service account ID"), tenantId: str("Tenant ID (optional)") },
+    "serviceAccountId"
+  )).response(200, "Role unbound", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("unbindRoleFromServiceAccount").build(),
+  bindPermissionToServiceAccount: endpoint("POST", "/iam/permissions/bind/service-account").summary("Bind permission directly to a service account").tags("IAM", "Permissions", "Service Accounts").security("bearer").permission("fortress", "managePermissions").body(obj(
+    {
+      serviceAccountId: id("Service account ID"),
+      permission: iamRef("PermissionInput"),
+      tenantId: str("Tenant ID (optional)")
+    },
+    "serviceAccountId",
+    "permission"
+  )).response(200, "Permission bound", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("bindPermissionToServiceAccount").build(),
+  unbindPermissionFromServiceAccount: endpoint("DELETE", "/iam/permissions/bind/service-account").summary("Unbind permission from a service account").tags("IAM", "Permissions", "Service Accounts").security("bearer").permission("fortress", "managePermissions").body(obj(
+    {
+      serviceAccountId: id("Service account ID"),
+      permissionId: id("Permission ID"),
+      tenantId: str("Tenant ID (optional)")
+    },
+    "serviceAccountId",
+    "permissionId"
+  )).response(200, "Permission unbound", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", authRef("ErrorResponse")).handler("unbindPermissionFromServiceAccount").build()
+};
+
+// src/plugins/openapi/spec-builder.ts
+var SECURITY_SCHEMES = {
+  bearer: { type: "http", scheme: "bearer", bearerFormat: "JWT" },
+  basic: { type: "http", scheme: "basic" },
+  apiKey: { type: "apiKey", name: "X-API-Key", in: "header" }
+};
+var SECURITY_MAP = {
+  bearer: { bearerAuth: [] },
+  basic: { basicAuth: [] },
+  apiKey: { apiKeyAuth: [] },
+  none: {}
+};
+var RE_LEADING_SLASH = /^\//;
+var RE_PARAM_COLON = /\/:(\w+)/g;
+var RE_SLASH = /\//g;
+var RE_NON_WORD = /\W/g;
+function toOperationId(method, path) {
+  const normalized = path.replace(RE_LEADING_SLASH, "").replace(RE_PARAM_COLON, "/$1").replace(RE_SLASH, "_").replace(RE_NON_WORD, "_");
+  return `${method.toLowerCase()}_${normalized}`;
+}
+function extractPathParams(path, paramSchemas) {
+  const params = [];
+  const matches = path.matchAll(/:(\w+)/g);
+  for (const match of matches) {
+    const name = match[1];
+    const schema = paramSchemas?.properties?.[name] ?? { type: "string" };
+    params.push({
+      name,
+      in: "path",
+      required: true,
+      description: schema.description,
+      schema: { type: schema.type ?? "string" }
+    });
+  }
+  return params;
+}
+function extractQueryParams(querySchema) {
+  if (!querySchema?.properties)
+    return [];
+  const params = [];
+  const required = new Set(querySchema.required ?? []);
+  for (const [name, schema] of Object.entries(querySchema.properties)) {
+    params.push({
+      name,
+      in: "query",
+      required: required.has(name),
+      description: schema.description,
+      schema
+    });
+  }
+  return params;
+}
+function toOpenAPIPath(path) {
+  return path.replace(/:(\w+)/g, "{$1}");
+}
+function cleanSchema(value) {
+  if (Array.isArray(value))
+    return value.map(cleanSchema);
+  if (typeof value === "object" && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value).filter(([key]) => !key.startsWith("~")).filter(([, entry]) => typeof entry !== "function" && entry !== void 0).map(([key, entry]) => [key, cleanSchema(entry)])
+    );
+  }
+  return value;
+}
+function resolveOperationId(endpoint2, options) {
+  if (typeof options.operationId === "function")
+    return options.operationId(endpoint2);
+  if (options.operationId === "handler")
+    return endpoint2.handler;
+  return toOperationId(endpoint2.method, endpoint2.path);
+}
+function buildOpenAPISpec(endpoints, componentSchemas, options) {
+  const paths = {};
+  const usedSecuritySchemes = /* @__PURE__ */ new Set();
+  for (const ep of endpoints) {
+    const openAPIPath = toOpenAPIPath(ep.path);
+    const method = ep.method.toLowerCase();
+    if (!paths[openAPIPath]) {
+      paths[openAPIPath] = {};
+    }
+    const operation = {
+      operationId: resolveOperationId(ep, options),
+      responses: {}
+    };
+    if (ep.meta) {
+      if (ep.meta.summary)
+        operation.summary = ep.meta.summary;
+      if (ep.meta.description)
+        operation.description = ep.meta.description;
+      if (ep.meta.tags)
+        operation.tags = ep.meta.tags;
+      if (ep.meta.deprecated)
+        operation.deprecated = true;
+      if (ep.meta.security) {
+        const secArr = [];
+        for (const s of ep.meta.security) {
+          if (s === "none") {
+            secArr.push({});
+          } else {
+            secArr.push(SECURITY_MAP[s]);
+            usedSecuritySchemes.add(s);
+          }
+        }
+        operation.security = secArr;
+      }
+    }
+    const params = [
+      ...extractPathParams(ep.path, cleanSchema(ep.input?.params)),
+      ...extractQueryParams(cleanSchema(ep.input?.query))
+    ];
+    if (params.length > 0) {
+      operation.parameters = params;
+    }
+    if (ep.input?.body) {
+      operation.requestBody = {
+        required: true,
+        content: { "application/json": { schema: cleanSchema(ep.input.body) } }
+      };
+    }
+    if (ep.responses) {
+      for (const [status, resp] of Object.entries(ep.responses)) {
+        const entry = {
+          description: resp.description
+        };
+        if (resp.schema) {
+          entry.content = { "application/json": { schema: cleanSchema(resp.schema) } };
+        }
+        operation.responses[status] = entry;
+      }
+    } else {
+      operation.responses["200"] = { description: "Success" };
+    }
+    paths[openAPIPath][method] = operation;
+  }
+  const securitySchemes = {};
+  const schemeNameMap = { bearer: "bearerAuth", basic: "basicAuth", apiKey: "apiKeyAuth" };
+  for (const scheme of usedSecuritySchemes) {
+    const name = schemeNameMap[scheme];
+    if (name && SECURITY_SCHEMES[scheme]) {
+      securitySchemes[name] = SECURITY_SCHEMES[scheme];
+    }
+  }
+  const spec = {
+    openapi: "3.1.0",
+    info: {
+      title: options.title,
+      version: options.version,
+      ...options.description && { description: options.description }
+    },
+    paths,
+    components: {
+      schemas: cleanSchema(componentSchemas),
+      securitySchemes
+    }
+  };
+  if (options.servers && options.servers.length > 0) {
+    spec.servers = options.servers;
+  }
+  if (options.tags && options.tags.length > 0) {
+    spec.tags = options.tags;
+  }
+  return spec;
+}
+
+// src/plugins/openapi/index.ts
+function computeRelativeUrl(fromPath, toPath) {
+  const fromParts = fromPath.split("/").slice(0, -1);
+  const toParts = toPath.split("/");
+  let common = 0;
+  while (common < fromParts.length && common < toParts.length && fromParts[common] === toParts[common]) {
+    common++;
+  }
+  const ups = fromParts.length - common;
+  const rest = toParts.slice(common).join("/");
+  if (ups === 0)
+    return `./${rest}`;
+  return "../".repeat(ups) + rest;
+}
+function buildScalarHTML(specPath, title) {
+  return `<!DOCTYPE html>
+<html>
+<head>
+  <title>${title} \u2014 API Reference</title>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+</head>
+<body>
+  <script id="api-reference" data-url="${specPath}"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+</body>
+</html>`;
+}
+function buildResourceBranch(resourceName, actions, sharedProps, requiredFields) {
+  const actionSchema = actions.length > 0 ? { type: "string", enum: actions, description: "Action name" } : { type: "string", description: "Action name" };
+  return {
+    type: "object",
+    properties: {
+      resource: { type: "string", const: resourceName, description: "Resource name" },
+      action: actionSchema,
+      ...sharedProps
+    },
+    required: requiredFields
+  };
+}
+function enrichIamSchemas(componentSchemas, allEndpoints, resourceFile) {
+  const entries = Object.entries(resourceFile.resources);
+  if (entries.length === 0)
+    return;
+  const permissionShared = {
+    id: { type: "integer", description: "Permission ID" },
+    effect: { type: "string", enum: ["ALLOW", "DENY"] },
+    conditions: componentSchemas.Permission?.properties?.conditions ?? { type: "array" },
+    description: { type: "string", description: "Permission description", nullable: true }
+  };
+  const permissionInputShared = {
+    effect: { type: "string", enum: ["ALLOW", "DENY"] },
+    conditions: componentSchemas.PermissionInput?.properties?.conditions ?? { type: "array" }
+  };
+  const permissionBranches = [];
+  const permissionInputBranches = [];
+  for (const [name, def] of entries) {
+    permissionBranches.push(
+      buildResourceBranch(name, def.actions, permissionShared, ["id", "resource", "action", "effect"])
+    );
+    permissionInputBranches.push(
+      buildResourceBranch(name, def.actions, permissionInputShared, ["resource", "action"])
+    );
+  }
+  componentSchemas.Permission = { oneOf: permissionBranches };
+  componentSchemas.PermissionInput = { oneOf: permissionInputBranches };
+  const allResourceNames = entries.map(([name]) => name).sort();
+  const allActions = [...new Set(entries.flatMap(([, def]) => def.actions))].sort();
+  for (const ep of allEndpoints) {
+    if (ep.path === "/iam/check" && ep.input?.body?.properties) {
+      const bodyClone = JSON.parse(JSON.stringify(ep.input.body));
+      if (bodyClone.properties.resource) {
+        bodyClone.properties.resource = { ...bodyClone.properties.resource, enum: allResourceNames };
+      }
+      if (bodyClone.properties.action && allActions.length > 0) {
+        bodyClone.properties.action = { ...bodyClone.properties.action, enum: allActions };
+      }
+      ep.input = { ...ep.input, body: bodyClone };
+      break;
+    }
+  }
+}
+function openapi(config = {}) {
+  const specPath = config.specPath ?? "/openapi.json";
+  const uiPath = config.uiPath ?? "/openapi";
+  const title = config.title ?? "Fortress Auth API";
+  const version = config.version ?? "1.0.0";
+  let cachedSpec = null;
+  const routes = {
+    getSpec: {
+      method: "GET",
+      path: specPath,
+      handler: "getSpec",
+      meta: { summary: "OpenAPI specification", tags: ["OpenAPI"], security: ["none"] },
+      responses: { 200: { description: "OpenAPI 3.1 JSON spec" } }
+    }
+  };
+  if (!config.disableUI) {
+    routes.getUI = {
+      method: "GET",
+      path: uiPath,
+      handler: "getUI",
+      meta: { summary: "API reference (Scalar)", tags: ["OpenAPI"], security: ["none"] },
+      responses: { 200: { description: "Scalar API reference HTML" } }
+    };
+  }
+  return {
+    name: "openapi",
+    routes,
+    methods: (ctx) => {
+      async function generateSpec() {
+        if (cachedSpec)
+          return cachedSpec;
+        const allEndpoints = [];
+        const plugins = ctx.config.plugins ?? [];
+        if (config.includeCoreAuth !== false) {
+          allEndpoints.push(...Object.values(authEndpoints));
+        }
+        if (config.includeCoreIam !== false) {
+          allEndpoints.push(...Object.values(iamEndpoints));
+        }
+        if (ctx.config.routes) {
+          allEndpoints.push(...Object.values(ctx.config.routes));
+        }
+        for (const plugin of plugins) {
+          if (plugin.name === "openapi" || !plugin.routes)
+            continue;
+          allEndpoints.push(...Object.values(plugin.routes));
+        }
+        if (config.additionalEndpoints) {
+          allEndpoints.push(...config.additionalEndpoints);
+        }
+        const componentSchemas = {
+          ...config.includeCoreAuth !== false ? authComponentSchemas : {},
+          ...config.includeCoreIam !== false ? iamComponentSchemas : {},
+          ...config.additionalSchemas ?? {}
+        };
+        if (config.includeCoreIam !== false && ctx.iam) {
+          try {
+            const resourceFile = await ctx.iam.getResources();
+            enrichIamSchemas(componentSchemas, allEndpoints, resourceFile);
+          } catch {
+          }
+        }
+        cachedSpec = buildOpenAPISpec(allEndpoints, componentSchemas, {
+          title,
+          version,
+          description: config.description,
+          servers: config.servers,
+          tags: config.tags,
+          operationId: config.operationId
+        });
+        return cachedSpec;
+      }
+      return {
+        generateSpec,
+        async getSpec() {
+          return await generateSpec();
+        },
+        getUI() {
+          return buildScalarHTML(computeRelativeUrl(uiPath, specPath), title);
+        }
+      };
+    }
+  };
+}
+export {
+  openapi
+};