@bajustone/fortress 1.0.0-rc.1

package/dist/plugins/admin.js

@@ -0,0 +1,2351 @@
+// 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/errors.ts
+var FortressError = class extends Error {
+  code;
+  statusCode;
+  retryAfter;
+  details;
+  /** RFC 6749 §5.2 / §4.1.2.1 machine code. Set by `Errors.oauth()`. */
+  oauthError;
+  /** Human-readable description for the OAuth `error_description` field. */
+  oauthDescription;
+  /** Optional URI for the OAuth `error_uri` field (§5.2). */
+  oauthErrorUri;
+  constructor(code, message, statusCode, options) {
+    super(message, { cause: options?.cause });
+    this.code = code;
+    this.statusCode = statusCode;
+    this.retryAfter = options?.retryAfter;
+    this.details = options?.details;
+    this.oauthError = options?.oauthError;
+    this.oauthDescription = options?.oauthDescription;
+    this.oauthErrorUri = options?.oauthErrorUri;
+  }
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      ...this.details !== void 0 && { details: this.details }
+    };
+  }
+};
+var Errors = {
+  unauthorized: (message = "Unauthorized") => new FortressError("UNAUTHORIZED", message, 401),
+  tokenReuse: () => new FortressError("TOKEN_REUSE", "Token reuse detected", 401),
+  sessionIdleTimeout: () => new FortressError("SESSION_IDLE_TIMEOUT", "Session idle timeout exceeded", 401),
+  sessionAbsoluteTimeout: () => new FortressError("SESSION_ABSOLUTE_TIMEOUT", "Session absolute timeout exceeded", 401),
+  forbidden: (message = "Forbidden") => new FortressError("FORBIDDEN", message, 403),
+  badRequest: (message = "Bad request") => new FortressError("BAD_REQUEST", message, 400),
+  notFound: (message = "Not found") => new FortressError("NOT_FOUND", message, 404),
+  conflict: (message = "Conflict", options) => new FortressError("CONFLICT", message, 409, options),
+  unprocessable: (message = "Unprocessable entity", options) => new FortressError("UNPROCESSABLE_ENTITY", message, 422, options),
+  rateLimited: (retryAfter) => new FortressError("RATE_LIMITED", "Too many requests", 429, { retryAfter }),
+  database: (message = "Database error", cause) => new FortressError("DATABASE_ERROR", message, 500, { cause }),
+  serviceUnavailable: (message = "Service unavailable", options) => new FortressError("SERVICE_UNAVAILABLE", message, 503, options),
+  validationError: (issues) => new FortressError("VALIDATION_ERROR", "Validation failed", 422, { details: issues }),
+  /**
+   * RFC 6749 §5.2 / §4.1.2.1 OAuth error.
+   *
+   * The HTTP error mapper detects `oauthError` and emits the OAuth-spec
+   * JSON body `{ error, error_description, error_uri? }` instead of the
+   * default fortress `{ code, message }` shape, so strict OAuth clients
+   * (Moodle, openid-client, Spring Security, etc.) can switch behaviour
+   * on the machine-readable `error` field.
+   *
+   * Status is inferred from the OAuth code per the spec table:
+   * - `invalid_client` → 401
+   * - everything else → 400
+   */
+  oauth: (error, description, options) => {
+    const status = options?.status ?? (error === "invalid_client" ? 401 : 400);
+    const code = status === 401 ? "UNAUTHORIZED" : "BAD_REQUEST";
+    return new FortressError(code, description ?? error, status, {
+      oauthError: error,
+      oauthDescription: description,
+      oauthErrorUri: options?.errorUri,
+      cause: options?.cause
+    });
+  },
+  /**
+   * Reconstruct a {@link FortressError} from a JSON error body emitted by
+   * `errorToResponse`. Used by the in-process `fortress.call.*` client to
+   * convert non-2xx responses into typed throws that mirror what a direct
+   * service-method call would produce.
+   *
+   * Maps by HTTP status when the body doesn't carry a recognizable
+   * `{ code, message }` payload, so network errors and opaque upstream
+   * failures still become structured `FortressError`s.
+   */
+  fromHttpResponse: (status, body) => {
+    const payload = body && typeof body === "object" ? body : {};
+    const message = typeof payload.message === "string" ? payload.message : `HTTP ${status}`;
+    const code = typeof payload.code === "string" && isFortressErrorCode(payload.code) ? payload.code : statusToErrorCode(status);
+    return new FortressError(code, message, status, { details: payload.details });
+  }
+};
+function isFortressErrorCode(code) {
+  return code === "UNAUTHORIZED" || code === "TOKEN_REUSE" || code === "SESSION_IDLE_TIMEOUT" || code === "SESSION_ABSOLUTE_TIMEOUT" || code === "FORBIDDEN" || code === "BAD_REQUEST" || code === "NOT_FOUND" || code === "CONFLICT" || code === "UNPROCESSABLE_ENTITY" || code === "RATE_LIMITED" || code === "DATABASE_ERROR" || code === "VALIDATION_ERROR" || code === "SERVICE_UNAVAILABLE";
+}
+function statusToErrorCode(status) {
+  if (status === 401)
+    return "UNAUTHORIZED";
+  if (status === 403)
+    return "FORBIDDEN";
+  if (status === 404)
+    return "NOT_FOUND";
+  if (status === 409)
+    return "CONFLICT";
+  if (status === 422)
+    return "UNPROCESSABLE_ENTITY";
+  if (status === 429)
+    return "RATE_LIMITED";
+  if (status === 503)
+    return "SERVICE_UNAVAILABLE";
+  if (status >= 500)
+    return "DATABASE_ERROR";
+  return "BAD_REQUEST";
+}
+
+// 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/core/iam/resource-sync.ts
+async function pullResources(db) {
+  const resources = await db.findMany({
+    model: "resource",
+    sortBy: { field: "name", direction: "asc" }
+  });
+  const result = { resources: {} };
+  for (const resource of resources) {
+    const permissions = await db.findMany({
+      model: "permission",
+      where: [{ field: "resource", operator: "=", value: resource.name }],
+      sortBy: { field: "id", direction: "asc" }
+    });
+    result.resources[resource.name] = {
+      actions: permissions.map((p) => p.action),
+      ...resource.description ? { description: resource.description } : {}
+    };
+  }
+  return result;
+}
+
+// src/plugins/api-key/core.ts
+function toInfo(r) {
+  return {
+    id: r.id,
+    name: r.name,
+    keyPrefix: r.keyPrefix,
+    scopes: r.scopes ? JSON.parse(r.scopes) : null,
+    expiresAt: r.expiresAt,
+    lastUsedAt: r.lastUsedAt,
+    createdAt: r.createdAt
+  };
+}
+function subjectWhere(subject) {
+  return [
+    { field: "subjectType", operator: "=", value: subject.type },
+    { field: "subjectId", operator: "=", value: subject.id }
+  ];
+}
+async function listKeysForSubject(db, subject) {
+  const records = await db.findMany({
+    model: "api_key",
+    where: [
+      ...subjectWhere(subject),
+      { field: "isRevoked", operator: "=", value: false }
+    ]
+  });
+  return records.map(toInfo);
+}
+async function revokeKeyAsAdmin(db, keyId) {
+  const record2 = await db.findOne({
+    model: "api_key",
+    where: [{ field: "id", operator: "=", value: keyId }]
+  });
+  if (!record2)
+    throw Errors.notFound("API key not found");
+  await db.update({
+    model: "api_key",
+    where: [{ field: "id", operator: "=", value: keyId }],
+    data: { isRevoked: true }
+  });
+}
+
+// src/plugins/admin/index.ts
+function collectPermissions(endpoints) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const ep of endpoints) {
+    const perm = ep.meta?.permission;
+    if (!perm)
+      continue;
+    const key = `${perm.resource}:${perm.action}`;
+    if (seen.has(key))
+      continue;
+    seen.add(key);
+    result.push(perm);
+  }
+  return result;
+}
+var userRef = { $ref: "#/components/schemas/User" };
+var permissionRef = { $ref: "#/components/schemas/Permission" };
+var permissionInputRef = { $ref: "#/components/schemas/PermissionInput" };
+var errorRef = { $ref: "#/components/schemas/ErrorResponse" };
+function intSchema(desc) {
+  return { type: "integer", description: desc };
+}
+function strSchema(desc) {
+  return { type: "string", description: desc };
+}
+function boolSchema(desc) {
+  return { type: "boolean", description: desc };
+}
+var encoder = new TextEncoder();
+function timingSafeEqual(a, b) {
+  const left = encoder.encode(a);
+  const right = encoder.encode(b);
+  const len = Math.max(left.length, right.length);
+  let diff = left.length ^ right.length;
+  for (let i = 0; i < len; i++)
+    diff |= (left[i] ?? 0) ^ (right[i] ?? 0);
+  return diff === 0;
+}
+function requireId(v, name) {
+  if (v == null || v === "")
+    throw Errors.badRequest(`${name} is required`);
+  if (typeof v === "string")
+    return v;
+  if (typeof v === "number" && Number.isFinite(v))
+    return String(v);
+  throw Errors.badRequest(`${name} must be a string or number`);
+}
+var adminAuthEndpoints = [
+  // GET /auth/users — list users (paginated, searchable)
+  {
+    method: "GET",
+    path: "/auth/users",
+    handler: "listUsers",
+    meta: {
+      summary: "List users",
+      description: "List all users with pagination and optional search",
+      tags: ["Auth", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "viewUsers" }
+    },
+    input: {
+      query: {
+        type: "object",
+        properties: {
+          limit: intSchema("Max results (default 50)"),
+          offset: intSchema("Skip results (default 0)"),
+          search: strSchema("Search by email"),
+          sortBy: strSchema("Sort field (default: id)"),
+          sortDirection: { type: "string", enum: ["asc", "desc"], description: "Sort direction" }
+        }
+      }
+    },
+    responses: {
+      200: {
+        description: "User list",
+        schema: {
+          type: "object",
+          properties: {
+            users: { type: "array", items: userRef, description: "List of users" },
+            total: intSchema("Total number of users")
+          },
+          required: ["users", "total"]
+        }
+      },
+      401: { description: "Not authenticated" },
+      403: { description: "Insufficient permissions" }
+    }
+  },
+  // GET /auth/users/:id — get user by ID
+  {
+    method: "GET",
+    path: "/auth/users/:id",
+    handler: "getUserById",
+    meta: {
+      summary: "Get user by ID",
+      tags: ["Auth", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "viewUsers" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { id: intSchema("User ID") },
+        required: ["id"]
+      }
+    },
+    responses: {
+      200: { description: "User details", schema: userRef },
+      401: { description: "Not authenticated" },
+      403: { description: "Insufficient permissions" },
+      404: { description: "User not found", schema: errorRef }
+    }
+  },
+  // PUT /auth/users/:id — update user
+  {
+    method: "PUT",
+    path: "/auth/users/:id",
+    handler: "updateUser",
+    meta: {
+      summary: "Update user",
+      tags: ["Auth", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "manageUsers" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { id: intSchema("User ID") },
+        required: ["id"]
+      },
+      body: {
+        type: "object",
+        properties: {
+          name: strSchema("Display name"),
+          email: { type: "string", format: "email", description: "User email" },
+          isActive: boolSchema("Account active status"),
+          password: strSchema("New password (will be hashed)")
+        }
+      }
+    },
+    responses: {
+      200: { description: "Updated user", schema: userRef },
+      401: { description: "Not authenticated" },
+      403: { description: "Insufficient permissions" },
+      404: { description: "User not found", schema: errorRef },
+      409: { description: "Email already in use", schema: errorRef }
+    }
+  },
+  // DELETE /auth/users/:id — delete user
+  {
+    method: "DELETE",
+    path: "/auth/users/:id",
+    handler: "deleteUser",
+    meta: {
+      summary: "Delete user",
+      tags: ["Auth", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "manageUsers" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { id: intSchema("User ID") },
+        required: ["id"]
+      }
+    },
+    responses: {
+      200: { description: "User deleted", schema: { type: "object", properties: { ok: boolSchema("Success") } } },
+      401: { description: "Not authenticated" },
+      403: { description: "Insufficient permissions" },
+      404: { description: "User not found", schema: errorRef }
+    }
+  },
+  // POST /auth/users — admin-initiated user creation
+  {
+    method: "POST",
+    path: "/auth/users",
+    handler: "createUser",
+    meta: {
+      summary: "Create a user (admin)",
+      description: "Admin-initiated user creation. Unlike /auth/register, requires authentication and manageUsers permission.",
+      tags: ["Auth", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "manageUsers" }
+    },
+    input: {
+      body: {
+        type: "object",
+        properties: {
+          email: { type: "string", format: "email", description: "User email" },
+          name: strSchema("Display name"),
+          password: strSchema("User password"),
+          isActive: boolSchema("Set active status (default true)")
+        },
+        required: ["email", "name"]
+      }
+    },
+    responses: {
+      201: { description: "User created", schema: userRef },
+      401: { description: "Not authenticated" },
+      403: { description: "Insufficient permissions" },
+      409: { description: "Email already exists", schema: errorRef }
+    }
+  }
+];
+var adminIamEndpoints = [
+  // GET /iam/roles/:id — get role with permissions
+  {
+    method: "GET",
+    path: "/iam/roles/:id",
+    handler: "getRole",
+    meta: {
+      summary: "Get role with permissions",
+      tags: ["IAM", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "viewRoles" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { id: intSchema("Role ID") },
+        required: ["id"]
+      }
+    },
+    responses: {
+      200: {
+        description: "Role with permissions",
+        schema: {
+          type: "object",
+          properties: {
+            id: intSchema("Role ID"),
+            name: strSchema("Role name"),
+            description: { type: "string", nullable: true, description: "Role description" },
+            isSystem: boolSchema("Whether this is a system role"),
+            permissions: { type: "array", items: permissionRef, description: "Role permissions" }
+          },
+          required: ["id", "name", "permissions"]
+        }
+      },
+      404: { description: "Role not found", schema: errorRef }
+    }
+  },
+  // PUT /iam/roles/:id — update role
+  {
+    method: "PUT",
+    path: "/iam/roles/:id",
+    handler: "updateRole",
+    meta: {
+      summary: "Update role",
+      tags: ["IAM", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "manageRoles" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { id: intSchema("Role ID") },
+        required: ["id"]
+      },
+      body: {
+        type: "object",
+        properties: {
+          name: strSchema("Role name"),
+          description: strSchema("Role description")
+        }
+      }
+    },
+    responses: {
+      200: { description: "Updated role", schema: { $ref: "#/components/schemas/Role" } },
+      400: { description: "Cannot update system role", schema: errorRef },
+      404: { description: "Role not found", schema: errorRef }
+    }
+  },
+  // GET /iam/groups — list groups (paginated)
+  {
+    method: "GET",
+    path: "/iam/groups",
+    handler: "listGroups",
+    meta: {
+      summary: "List groups",
+      tags: ["IAM", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "viewGroups" }
+    },
+    input: {
+      query: {
+        type: "object",
+        properties: {
+          limit: intSchema("Max results (default 50)"),
+          offset: intSchema("Skip results (default 0)")
+        }
+      }
+    },
+    responses: {
+      200: {
+        description: "Group list",
+        schema: {
+          type: "object",
+          properties: {
+            groups: { type: "array", items: { $ref: "#/components/schemas/Group" }, description: "List of groups" },
+            total: intSchema("Total number of groups")
+          },
+          required: ["groups", "total"]
+        }
+      }
+    }
+  },
+  // GET /iam/groups/:id — get group with members
+  {
+    method: "GET",
+    path: "/iam/groups/:id",
+    handler: "getGroup",
+    meta: {
+      summary: "Get group with members",
+      tags: ["IAM", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "viewGroups" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { id: intSchema("Group ID") },
+        required: ["id"]
+      }
+    },
+    responses: {
+      200: {
+        description: "Group with members",
+        schema: {
+          type: "object",
+          properties: {
+            id: intSchema("Group ID"),
+            name: strSchema("Group name"),
+            description: { type: "string", nullable: true, description: "Group description" },
+            users: { type: "array", items: userRef, description: "Group members" }
+          },
+          required: ["id", "name", "users"]
+        }
+      },
+      404: { description: "Group not found", schema: errorRef }
+    }
+  },
+  // PUT /iam/groups/:id — update group
+  {
+    method: "PUT",
+    path: "/iam/groups/:id",
+    handler: "updateGroup",
+    meta: {
+      summary: "Update group",
+      tags: ["IAM", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "manageGroup" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { id: intSchema("Group ID") },
+        required: ["id"]
+      },
+      body: {
+        type: "object",
+        properties: {
+          name: strSchema("Group name"),
+          description: strSchema("Group description")
+        }
+      }
+    },
+    responses: {
+      200: { description: "Updated group", schema: { $ref: "#/components/schemas/Group" } },
+      404: { description: "Group not found", schema: errorRef }
+    }
+  },
+  // DELETE /iam/groups/:id — delete group
+  {
+    method: "DELETE",
+    path: "/iam/groups/:id",
+    handler: "deleteGroup",
+    meta: {
+      summary: "Delete group",
+      tags: ["IAM", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "manageGroup" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { id: intSchema("Group ID") },
+        required: ["id"]
+      }
+    },
+    responses: {
+      200: { description: "Group deleted", schema: { type: "object", properties: { ok: boolSchema("Success") } } },
+      404: { description: "Group not found", schema: errorRef }
+    }
+  },
+  // GET /iam/groups/:id/users — list group members
+  {
+    method: "GET",
+    path: "/iam/groups/:id/users",
+    handler: "getGroupUsers",
+    meta: {
+      summary: "List group members",
+      tags: ["IAM", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "viewGroups" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { id: intSchema("Group ID") },
+        required: ["id"]
+      }
+    },
+    responses: {
+      200: {
+        description: "Group members",
+        schema: { type: "array", items: userRef }
+      }
+    }
+  },
+  // GET /iam/permissions — list all permissions
+  {
+    method: "GET",
+    path: "/iam/permissions",
+    handler: "listPermissions",
+    meta: {
+      summary: "List permissions",
+      tags: ["IAM", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "viewPermissions" }
+    },
+    input: {
+      query: {
+        type: "object",
+        properties: {
+          resource: strSchema("Filter by resource name")
+        }
+      }
+    },
+    responses: {
+      200: {
+        description: "Permission list",
+        schema: { type: "array", items: permissionRef }
+      }
+    }
+  },
+  // POST /iam/permissions — create permission
+  {
+    method: "POST",
+    path: "/iam/permissions",
+    handler: "createPermission",
+    meta: {
+      summary: "Create permission",
+      tags: ["IAM", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "managePermissions" }
+    },
+    input: {
+      body: permissionInputRef
+    },
+    responses: {
+      200: { description: "Created permission", schema: permissionRef }
+    }
+  },
+  // DELETE /iam/permissions/:id — delete permission
+  {
+    method: "DELETE",
+    path: "/iam/permissions/:id",
+    handler: "deletePermission",
+    meta: {
+      summary: "Delete permission",
+      tags: ["IAM", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "managePermissions" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { id: intSchema("Permission ID") },
+        required: ["id"]
+      }
+    },
+    responses: {
+      200: { description: "Permission deleted", schema: { type: "object", properties: { ok: boolSchema("Success") } } },
+      404: { description: "Permission not found", schema: errorRef }
+    }
+  },
+  // POST /iam/roles/:id/permissions — add permission to role
+  {
+    method: "POST",
+    path: "/iam/roles/:id/permissions",
+    handler: "addPermissionToRole",
+    meta: {
+      summary: "Add permission to role",
+      tags: ["IAM", "Admin"],
+      security: ["bearer"],
+      permission: { resource: "fortress", action: "manageRoles" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { id: intSchema("Role ID") },
+        required: ["id"]
+      },
+      body: permissionInputRef
+    },
+    responses: {
+      200: { description: "Permission added", schema: { type: "object", properties: { ok: boolSchema("Success") } } },
+      404: { description: "Role not found", schema: errorRef }
+    }
+  }
+];
+var syncEndpoint = {
+  method: "POST",
+  path: "/iam/sync",
+  handler: "syncResources",
+  meta: {
+    summary: "Sync IAM resources",
+    description: "Push or pull resource definitions to/from the resource file",
+    tags: ["IAM", "Admin"],
+    security: ["bearer"],
+    permission: { resource: "fortress", action: "managePermissions" }
+  },
+  input: {
+    body: {
+      type: "object",
+      properties: {
+        direction: { type: "string", enum: ["push", "pull"], description: "Sync direction" },
+        filePath: strSchema("Resource file path (optional)")
+      },
+      required: ["direction"]
+    }
+  },
+  responses: {
+    200: { description: "Sync complete", schema: { type: "object", properties: { ok: boolSchema("Success") } } },
+    401: { description: "Not authenticated" },
+    403: { description: "Insufficient permissions" }
+  }
+};
+var bootstrapEndpoint = {
+  method: "POST",
+  path: "/iam/admin/bootstrap",
+  handler: "bootstrap",
+  meta: {
+    summary: "Bootstrap admin user",
+    description: "Opt-in emergency bootstrap. Assigns all fortress admin permissions only while zero fortress-admin bindings exist and only when the caller presents the one-time bootstrap secret. Creates the fortress resource and permissions if they do not exist.",
+    tags: ["IAM", "Admin"],
+    security: ["bearer"]
+  },
+  input: {
+    body: {
+      type: "object",
+      properties: {
+        userId: { type: "integer", description: "Target user ID. Defaults to the authenticated caller." },
+        secret: { type: "string", description: "One-time bootstrap secret" }
+      }
+    }
+  },
+  responses: {
+    200: { description: "Admin bootstrapped", schema: { type: "object", properties: { ok: { type: "boolean" }, role: { type: "object" } } } },
+    401: { description: "Not authenticated" },
+    403: { description: "Bootstrap disabled, bad secret, or already bootstrapped" }
+  }
+};
+var apiKeyInfoSchema = {
+  type: "object",
+  properties: {
+    id: intSchema("Database id"),
+    name: strSchema("Key label"),
+    keyPrefix: strSchema("First 12 characters of the key, for identification"),
+    scopes: { type: "array", items: { type: "string" }, nullable: true },
+    expiresAt: { type: "string", format: "date-time", nullable: true },
+    lastUsedAt: { type: "string", format: "date-time", nullable: true },
+    createdAt: { type: "string", format: "date-time" }
+  },
+  required: ["id", "name", "keyPrefix", "createdAt"]
+};
+var createKeyBodySchema = {
+  type: "object",
+  properties: {
+    name: strSchema("Human-readable key label"),
+    scopes: { type: "array", items: { type: "string" }, description: "Optional permission scopes attached to the key" },
+    expiresAt: { type: "string", description: "Optional expiry (ISO 8601 string)" }
+  },
+  required: ["name"]
+};
+var createKeyResponseSchema = {
+  type: "object",
+  properties: {
+    key: strSchema("Raw API key \u2014 shown exactly once, store it immediately"),
+    id: intSchema("Database id of the key")
+  },
+  required: ["key", "id"]
+};
+var adminApiKeyEndpoints = [
+  // ── User-scoped admin api-key management ──────────────────────
+  {
+    method: "POST",
+    path: "/admin/users/:userId/api-keys",
+    handler: "adminCreateUserApiKey",
+    meta: {
+      summary: "Mint an API key for any user",
+      description: "Create a new API key owned by any user, bypassing the self-service `maxKeysPerSubject` check is NOT done \u2014 the same limit applies. The raw key is returned exactly once and cannot be retrieved later. Requires the `apiKey:manage` permission. Typical use: provisioning keys during tenant onboarding or replacing a lost key on a user's behalf.",
+      tags: ["Admin", "API Keys"],
+      security: ["bearer"],
+      permission: { resource: "apiKey", action: "manage" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { userId: intSchema("Target user ID") },
+        required: ["userId"]
+      },
+      body: createKeyBodySchema
+    },
+    responses: {
+      201: { description: "Key created", schema: createKeyResponseSchema },
+      400: { description: "Bad request", schema: errorRef },
+      401: { description: "Not authenticated", schema: errorRef },
+      403: { description: "Forbidden", schema: errorRef },
+      404: { description: "User not found", schema: errorRef }
+    }
+  },
+  {
+    method: "GET",
+    path: "/admin/users/:userId/api-keys",
+    handler: "adminListUserApiKeys",
+    meta: {
+      summary: "List a user's API keys",
+      description: "Return the active (non-revoked) API keys belonging to any user. Raw keys and hashes are never returned. Requires the `apiKey:manage` permission.",
+      tags: ["Admin", "API Keys"],
+      security: ["bearer"],
+      permission: { resource: "apiKey", action: "manage" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { userId: intSchema("Target user ID") },
+        required: ["userId"]
+      }
+    },
+    responses: {
+      200: {
+        description: "Keys",
+        schema: {
+          type: "object",
+          properties: {
+            keys: { type: "array", items: apiKeyInfoSchema }
+          },
+          required: ["keys"]
+        }
+      },
+      401: { description: "Not authenticated", schema: errorRef },
+      403: { description: "Forbidden", schema: errorRef }
+    }
+  },
+  {
+    method: "DELETE",
+    path: "/admin/users/:userId/api-keys/:id",
+    handler: "adminRevokeUserApiKey",
+    meta: {
+      summary: "Revoke a user's API key",
+      description: "Revoke any API key by id, bypassing the self-service ownership check. Requires the `apiKey:manage` permission. Typically used to respond to leaked keys or compromised accounts.",
+      tags: ["Admin", "API Keys"],
+      security: ["bearer"],
+      permission: { resource: "apiKey", action: "manage" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: {
+          userId: intSchema("Target user ID (for URL namespacing; ownership is not enforced)"),
+          id: intSchema("Key id to revoke")
+        },
+        required: ["userId", "id"]
+      }
+    },
+    responses: {
+      200: {
+        description: "Revoked",
+        schema: {
+          type: "object",
+          properties: { ok: boolSchema("Success") },
+          required: ["ok"]
+        }
+      },
+      401: { description: "Not authenticated", schema: errorRef },
+      403: { description: "Forbidden", schema: errorRef },
+      404: { description: "Not found", schema: errorRef }
+    }
+  },
+  // ── Service-account-scoped admin api-key management ───────────
+  //
+  // Service accounts have no login path — they can't self-mint their
+  // first key. These endpoints are the only supported way to bootstrap
+  // a service account's credentials.
+  {
+    method: "POST",
+    path: "/admin/service-accounts/:id/api-keys",
+    handler: "adminCreateServiceAccountApiKey",
+    meta: {
+      summary: "Mint an API key for a service account",
+      description: "Create a new API key owned by a service account. This is the primary entry point for bootstrapping a service account's credentials \u2014 a fresh service account has no way to authenticate until an admin mints its first key. The raw key is returned exactly once and cannot be retrieved later. Requires the `apiKey:manage` permission.",
+      tags: ["Admin", "API Keys", "Service Accounts"],
+      security: ["bearer"],
+      permission: { resource: "apiKey", action: "manage" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { id: intSchema("Target service account ID") },
+        required: ["id"]
+      },
+      body: createKeyBodySchema
+    },
+    responses: {
+      201: { description: "Key created", schema: createKeyResponseSchema },
+      400: { description: "Bad request", schema: errorRef },
+      401: { description: "Not authenticated", schema: errorRef },
+      403: { description: "Forbidden", schema: errorRef },
+      404: { description: "Service account not found", schema: errorRef }
+    }
+  },
+  {
+    method: "GET",
+    path: "/admin/service-accounts/:id/api-keys",
+    handler: "adminListServiceAccountApiKeys",
+    meta: {
+      summary: "List a service account's API keys",
+      description: "Return the active (non-revoked) API keys owned by a service account. Raw keys and hashes are never returned. Requires the `apiKey:manage` permission.",
+      tags: ["Admin", "API Keys", "Service Accounts"],
+      security: ["bearer"],
+      permission: { resource: "apiKey", action: "manage" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: { id: intSchema("Target service account ID") },
+        required: ["id"]
+      }
+    },
+    responses: {
+      200: {
+        description: "Keys",
+        schema: {
+          type: "object",
+          properties: {
+            keys: { type: "array", items: apiKeyInfoSchema }
+          },
+          required: ["keys"]
+        }
+      },
+      401: { description: "Not authenticated", schema: errorRef },
+      403: { description: "Forbidden", schema: errorRef }
+    }
+  },
+  {
+    method: "DELETE",
+    path: "/admin/service-accounts/:id/api-keys/:keyId",
+    handler: "adminRevokeServiceAccountApiKey",
+    meta: {
+      summary: "Revoke a service account's API key",
+      description: "Revoke any API key by id, bypassing the self-service ownership check. Requires the `apiKey:manage` permission.",
+      tags: ["Admin", "API Keys", "Service Accounts"],
+      security: ["bearer"],
+      permission: { resource: "apiKey", action: "manage" }
+    },
+    input: {
+      params: {
+        type: "object",
+        properties: {
+          id: intSchema("Target service account ID (for URL namespacing; ownership is not enforced)"),
+          keyId: intSchema("Key id to revoke")
+        },
+        required: ["id", "keyId"]
+      }
+    },
+    responses: {
+      200: {
+        description: "Revoked",
+        schema: {
+          type: "object",
+          properties: { ok: boolSchema("Success") },
+          required: ["ok"]
+        }
+      },
+      401: { description: "Not authenticated", schema: errorRef },
+      403: { description: "Forbidden", schema: errorRef },
+      404: { description: "Not found", schema: errorRef }
+    }
+  }
+];
+function admin(options = {}) {
+  const mountApiKeyRoutes = options.apiKeyRoutes === true;
+  const mountBootstrap = options.bootstrap?.enabled === true;
+  const bootstrapSecret = options.bootstrap?.secret ?? process.env.FORTRESS_ADMIN_BOOTSTRAP_SECRET;
+  return {
+    name: "admin",
+    // Admin routes are aggregated from several internal arrays into a
+    // record keyed by `${method}_${path}` so collisions with core handler
+    // names (e.g. `createUser` exists in both auth-endpoints.ts and admin)
+    // are impossible. Admin routes exist for default-deny protection and
+    // aren't exposed via the typed `fortress.call.*` surface.
+    routes: Object.fromEntries(
+      [
+        ...mountBootstrap ? [bootstrapEndpoint] : [],
+        syncEndpoint,
+        ...adminAuthEndpoints,
+        ...adminIamEndpoints,
+        ...Object.values(iamEndpoints),
+        ...mountApiKeyRoutes ? adminApiKeyEndpoints : []
+      ].map((ep) => [`${ep.method}_${ep.path}`, ep])
+    ),
+    methods: (ctx) => ({
+      async getResources() {
+        return pullResources(ctx.db);
+      },
+      async bootstrap(body, routeCtx) {
+        if (!mountBootstrap)
+          throw Errors.notFound("Admin bootstrap route is disabled");
+        if (!bootstrapSecret)
+          throw Errors.forbidden("Admin bootstrap secret is not configured");
+        if (!body.secret || !timingSafeEqual(body.secret, bootstrapSecret))
+          throw Errors.forbidden("Invalid admin bootstrap secret");
+        const callerId = routeCtx?.userId;
+        const userId = body.userId ?? callerId;
+        if (userId == null)
+          throw Errors.unauthorized("User not authenticated");
+        const db = ctx.db;
+        return db.transaction(async (tx) => {
+          if (tx.dialect === "pg" && tx.rawQuery)
+            await tx.rawQuery("SELECT pg_advisory_xact_lock(hashtext(?))", ["fortress-admin-bootstrap"]);
+          const user = await tx.findOne({
+            model: "user",
+            where: [{ field: "id", operator: "=", value: userId }]
+          });
+          if (!user) {
+            throw Errors.notFound("User not found");
+          }
+          const existingRole = await tx.findOne({
+            model: "role",
+            where: [{ field: "name", operator: "=", value: "fortress-admin" }]
+          });
+          if (existingRole) {
+            const existingAdmins = await tx.count({
+              model: "role_binding",
+              where: [{ field: "roleId", operator: "=", value: existingRole.id }]
+            });
+            if (existingAdmins > 0)
+              throw Errors.forbidden("Admin already bootstrapped");
+          }
+          const plugins = ctx.config.plugins ?? [];
+          const pluginEndpoints = [];
+          for (const plugin of plugins) {
+            if (plugin.routes)
+              pluginEndpoints.push(...Object.values(plugin.routes));
+          }
+          const allEndpoints = [
+            ...Object.values(authEndpoints),
+            ...Object.values(iamEndpoints),
+            ...pluginEndpoints
+          ];
+          const declaredPermissions = collectPermissions(allEndpoints);
+          const resources = new Set(declaredPermissions.map((p) => p.resource));
+          for (const resource of resources) {
+            const existing = await tx.findOne({
+              model: "resource",
+              where: [{ field: "name", operator: "=", value: resource }]
+            });
+            if (!existing) {
+              await tx.create({ model: "resource", data: { name: resource, description: `Auto-registered by admin plugin` } });
+            }
+          }
+          const permissionIds = [];
+          for (const perm of declaredPermissions) {
+            let existing = await tx.findOne({
+              model: "permission",
+              where: [
+                { field: "resource", operator: "=", value: perm.resource },
+                { field: "action", operator: "=", value: perm.action }
+              ]
+            });
+            if (!existing) {
+              existing = await tx.create({
+                model: "permission",
+                data: {
+                  resource: perm.resource,
+                  action: perm.action,
+                  effect: "ALLOW",
+                  description: `${perm.action} ${perm.resource}`
+                }
+              });
+            }
+            permissionIds.push(existing.id);
+          }
+          let adminRole = existingRole;
+          if (!adminRole) {
+            adminRole = await tx.create({
+              model: "role",
+              data: { name: "fortress-admin", description: "Full fortress administration", isSystem: true }
+            });
+          }
+          for (const permId of permissionIds) {
+            const existingLink = await tx.findOne({
+              model: "role_permission",
+              where: [
+                { field: "roleId", operator: "=", value: adminRole.id },
+                { field: "permissionId", operator: "=", value: permId }
+              ]
+            });
+            if (!existingLink) {
+              await tx.create({ model: "role_permission", data: { roleId: adminRole.id, permissionId: permId } });
+            }
+          }
+          const existingBinding = await tx.findOne({
+            model: "role_binding",
+            where: [
+              { field: "roleId", operator: "=", value: adminRole.id },
+              { field: "subjectType", operator: "=", value: "USER" },
+              { field: "subjectId", operator: "=", value: userId }
+            ]
+          });
+          if (!existingBinding) {
+            await tx.create({
+              model: "role_binding",
+              data: { roleId: adminRole.id, subjectType: "USER", subjectId: userId, tenantId: null }
+            });
+          }
+          return { ok: true, role: adminRole };
+        });
+      },
+      // ── Auth admin — delegates to core auth service ──────────
+      async listUsers(body) {
+        if (!ctx.auth)
+          throw Errors.database("Auth service not available");
+        return ctx.auth.listUsers({
+          limit: body.limit ? Number(body.limit) : void 0,
+          offset: body.offset ? Number(body.offset) : void 0,
+          search: body.search,
+          sortBy: body.sortBy,
+          sortDirection: body.sortDirection
+        });
+      },
+      async getUserById(body) {
+        if (!ctx.auth)
+          throw Errors.database("Auth service not available");
+        return ctx.auth.getUserById(requireId(body.id, "id"));
+      },
+      async createUser(body) {
+        if (!ctx.auth)
+          throw Errors.database("Auth service not available");
+        return ctx.auth.createUser({
+          email: body.email,
+          name: body.name,
+          password: body.password,
+          isActive: body.isActive
+        });
+      },
+      async updateUser(body) {
+        if (!ctx.auth)
+          throw Errors.database("Auth service not available");
+        const { id: id2, ...data } = body;
+        return ctx.auth.updateUser(requireId(id2, "id"), data);
+      },
+      async deleteUser(body) {
+        if (!ctx.auth)
+          throw Errors.database("Auth service not available");
+        await ctx.auth.deleteUser(requireId(body.id, "id"));
+        return { ok: true };
+      },
+      // ── IAM admin — delegates to core IAM service ────────────
+      async getRole(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.getRole(requireId(body.id, "id"));
+      },
+      async updateRole(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        const { id: id2, ...data } = body;
+        return ctx.iam.updateRole(requireId(id2, "id"), data);
+      },
+      async listGroups(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.listGroups({
+          limit: body.limit ? Number(body.limit) : void 0,
+          offset: body.offset ? Number(body.offset) : void 0
+        });
+      },
+      async getGroup(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.getGroup(requireId(body.id, "id"));
+      },
+      async updateGroup(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        const { id: id2, ...data } = body;
+        return ctx.iam.updateGroup(requireId(id2, "id"), data);
+      },
+      async deleteGroup(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.deleteGroup(requireId(body.id, "id"));
+        return { ok: true };
+      },
+      async getGroupUsers(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.getGroupUsers(requireId(body.id, "id"));
+      },
+      async listPermissions(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.listPermissions({
+          resource: body.resource || void 0
+        });
+      },
+      async createPermission(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.createPermission(body);
+      },
+      async deletePermission(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.deletePermission(requireId(body.id, "id"));
+        return { ok: true };
+      },
+      async addPermissionToRole(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        const { id: id2, ...permission } = body;
+        await ctx.iam.addPermissionToRole(requireId(id2, "id"), permission);
+        return { ok: true };
+      },
+      // ── Core IAM operations — previously spec-only ─────────────
+      async getRoles() {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.getRoles();
+      },
+      async createRole(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.createRole(
+          body.name,
+          body.permissions ?? [],
+          body.description
+        );
+      },
+      async deleteRole(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.deleteRole(requireId(body.id, "id"));
+        return { ok: true };
+      },
+      async bindRoleToUser(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.bindRoleToUser(
+          requireId(body.userId, "userId"),
+          requireId(body.id, "id"),
+          body.tenantId
+        );
+        return { ok: true };
+      },
+      async bindRoleToGroup(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.bindRoleToGroup(
+          requireId(body.groupId, "groupId"),
+          requireId(body.id, "id"),
+          body.tenantId
+        );
+        return { ok: true };
+      },
+      async unbindRole(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.unbindRole(
+          body.subjectType,
+          requireId(body.subjectId, "subjectId"),
+          requireId(body.id, "id"),
+          body.tenantId
+        );
+        return { ok: true };
+      },
+      async createGroup(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.createGroup(
+          body.name,
+          body.description
+        );
+      },
+      async addUserToGroup(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.addUserToGroup(
+          requireId(body.id, "id"),
+          requireId(body.userId, "userId")
+        );
+        return { ok: true };
+      },
+      async removeUserFromGroup(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.removeUserFromGroup(
+          requireId(body.id, "id"),
+          requireId(body.userId, "userId")
+        );
+        return { ok: true };
+      },
+      async getUserPermissions(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.getPermissionsForSubject(
+          { type: "USER", id: requireId(body.id, "id") },
+          body.tenantId
+        );
+      },
+      async checkPermission(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        const allowed = await ctx.iam.checkPermission(
+          { type: "USER", id: requireId(body.userId, "userId") },
+          body.resource,
+          body.action,
+          body.context
+        );
+        return { allowed };
+      },
+      async bindPermissionToUser(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.bindPermissionToUser(
+          requireId(body.userId, "userId"),
+          body.permission,
+          body.tenantId
+        );
+        return { ok: true };
+      },
+      async bindPermissionToGroup(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.bindPermissionToGroup(
+          requireId(body.groupId, "groupId"),
+          body.permission,
+          body.tenantId
+        );
+        return { ok: true };
+      },
+      async unbindPermissionFromUser(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.unbindPermissionFromUser(
+          requireId(body.userId, "userId"),
+          requireId(body.permissionId, "permissionId"),
+          body.tenantId
+        );
+        return { ok: true };
+      },
+      async unbindPermissionFromGroup(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.unbindPermissionFromGroup(
+          requireId(body.groupId, "groupId"),
+          requireId(body.permissionId, "permissionId"),
+          body.tenantId
+        );
+        return { ok: true };
+      },
+      // ── Service-account IAM proxies ────────────────────────────
+      //
+      // The admin plugin re-exports `iamEndpoints` on its own `routes` so
+      // that IAM routes get dispatched through `dispatchPlugin`. That
+      // means every IAM handler referenced by those endpoint definitions
+      // must exist on this plugin's methods object — thin proxies that
+      // delegate to `ctx.iam`. Without these, hitting any
+      // `/iam/service-accounts/*` route through an instance that has the
+      // admin plugin registered returns a 404 from the dispatcher.
+      async createServiceAccount(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.createServiceAccount({
+          name: String(body.name ?? ""),
+          displayName: body.displayName,
+          description: body.description
+        });
+      },
+      async listServiceAccounts(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.listServiceAccounts({
+          limit: body.limit != null ? Number(body.limit) : void 0,
+          offset: body.offset != null ? Number(body.offset) : void 0
+        });
+      },
+      async getServiceAccount(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.getServiceAccount(requireId(body.id, "id"));
+      },
+      async updateServiceAccount(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.updateServiceAccount(requireId(body.id, "id"), {
+          displayName: body.displayName,
+          description: body.description,
+          isActive: body.isActive
+        });
+      },
+      async deleteServiceAccount(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.deleteServiceAccount(requireId(body.id, "id"));
+        return { ok: true };
+      },
+      async getServiceAccountPermissions(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        return ctx.iam.getPermissionsForSubject(
+          { type: "SERVICE_ACCOUNT", id: requireId(body.id, "id") },
+          body.tenantId
+        );
+      },
+      async bindRoleToServiceAccount(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.bindRoleToServiceAccount(
+          requireId(body.serviceAccountId, "serviceAccountId"),
+          requireId(body.id, "id"),
+          body.tenantId
+        );
+        return { ok: true };
+      },
+      async unbindRoleFromServiceAccount(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.unbindRoleFromServiceAccount(
+          requireId(body.serviceAccountId, "serviceAccountId"),
+          requireId(body.id, "id"),
+          body.tenantId
+        );
+        return { ok: true };
+      },
+      async bindPermissionToServiceAccount(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.bindPermissionToServiceAccount(
+          requireId(body.serviceAccountId, "serviceAccountId"),
+          body.permission,
+          body.tenantId
+        );
+        return { ok: true };
+      },
+      async unbindPermissionFromServiceAccount(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.unbindPermissionFromServiceAccount(
+          requireId(body.serviceAccountId, "serviceAccountId"),
+          requireId(body.permissionId, "permissionId"),
+          body.tenantId
+        );
+        return { ok: true };
+      },
+      // ── Admin api-key management ───────────────────────────────
+      //
+      // Read/delete delegate to the stateless helpers in `api-key/core.ts`.
+      // Create re-enters the api-key plugin's `methods` factory so the
+      // configured knobs (prefix, maxKeysPerSubject, defaultExpirySeconds)
+      // apply to admin-minted keys exactly as they do to self-service
+      // keys — no duplicate config. All of these are available as
+      // programmatic methods regardless of the `apiKeyRoutes` flag — only
+      // the HTTP mounting is gated. Requires the `api-key` plugin to be
+      // registered (for the `api_key` model).
+      async adminCreateUserApiKey(body) {
+        const userId = requireId(body.userId, "userId");
+        const user = await ctx.db.findOne({
+          model: "user",
+          where: [{ field: "id", operator: "=", value: userId }]
+        });
+        if (!user)
+          throw Errors.notFound("User not found");
+        const apiKeyMethods = getApiKeyMethods(ctx);
+        return apiKeyMethods.createKey({
+          subject: { type: "USER", id: userId },
+          name: String(body.name ?? ""),
+          scopes: Array.isArray(body.scopes) ? body.scopes.map(String) : void 0,
+          expiresAt: body.expiresAt
+        });
+      },
+      async adminListUserApiKeys(body) {
+        const keys = await listKeysForSubject(ctx.db, {
+          type: "USER",
+          id: requireId(body.userId, "userId")
+        });
+        return { keys };
+      },
+      async adminRevokeUserApiKey(body) {
+        await revokeKeyAsAdmin(ctx.db, requireId(body.id, "id"));
+        return { ok: true };
+      },
+      // ── Service-account-scoped admin api-key handlers ─────────
+      async adminCreateServiceAccountApiKey(body) {
+        const serviceAccountId = requireId(body.id, "id");
+        const sa = await ctx.db.findOne({
+          model: "service_account",
+          where: [{ field: "id", operator: "=", value: serviceAccountId }]
+        });
+        if (!sa)
+          throw Errors.notFound("Service account not found");
+        const apiKeyMethods = getApiKeyMethods(ctx);
+        return apiKeyMethods.createKey({
+          subject: { type: "SERVICE_ACCOUNT", id: serviceAccountId },
+          name: String(body.name ?? ""),
+          scopes: Array.isArray(body.scopes) ? body.scopes.map(String) : void 0,
+          expiresAt: body.expiresAt
+        });
+      },
+      async adminListServiceAccountApiKeys(body) {
+        const keys = await listKeysForSubject(ctx.db, {
+          type: "SERVICE_ACCOUNT",
+          id: requireId(body.id, "id")
+        });
+        return { keys };
+      },
+      async adminRevokeServiceAccountApiKey(body) {
+        await revokeKeyAsAdmin(ctx.db, requireId(body.keyId, "keyId"));
+        return { ok: true };
+      },
+      // ── Resource sync ──────────────────────────────────────────
+      async syncResources(body) {
+        if (!ctx.iam)
+          throw Errors.database("IAM service not available");
+        await ctx.iam.syncResources(
+          body.direction,
+          body.filePath
+        );
+        return { ok: true };
+      }
+    })
+  };
+}
+function getApiKeyMethods(ctx) {
+  const apiKeyPlugin = (ctx.config.plugins ?? []).find((p) => p.name === "api-key");
+  if (!apiKeyPlugin?.methods)
+    throw Errors.database("api-key plugin is not registered");
+  return apiKeyPlugin.methods(ctx);
+}
+export {
+  admin
+};