@bajustone/fortress 1.0.0-rc.1

package/dist/plugins/api-key.js

@@ -0,0 +1,765 @@
+// 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/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 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 ref(name, schema) {
+  assertComponentName(name);
+  const definitions = schema ? { [name]: schema } : void 0;
+  return toFortressSchema({ $ref: `#/components/schemas/${name}` }, definitions);
+}
+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/refresh-token.ts
+async function hashToken(raw) {
+  const data = new TextEncoder().encode(raw);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  return hexEncode(new Uint8Array(hashBuffer));
+}
+function hexEncode(bytes) {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/plugins/api-key/core.ts
+async function generateApiKey(prefix) {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  const random = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  const raw = `${prefix}_sk_${random}`;
+  const hash = await hashToken(raw);
+  const keyPrefix = `${prefix}_sk_${random.slice(0, 8)}`;
+  return { raw, hash, keyPrefix };
+}
+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 createKeyForSubject(db, subject, options, knobs) {
+  return db.transaction(async (tx) => {
+    if (tx.dialect === "pg" && tx.rawQuery) {
+      await tx.rawQuery("SELECT pg_advisory_xact_lock(hashtext(?), hashtext(?))", [subject.type, subject.id]);
+    }
+    const activeCount = await tx.count({
+      model: "api_key",
+      where: [
+        ...subjectWhere(subject),
+        { field: "isRevoked", operator: "=", value: false }
+      ]
+    });
+    if (activeCount >= knobs.maxKeysPerSubject) {
+      throw Errors.badRequest(`Maximum of ${knobs.maxKeysPerSubject} active API keys per subject`);
+    }
+    const { raw, hash, keyPrefix } = await generateApiKey(knobs.prefix);
+    let expiresAt = null;
+    if (options.expiresAt) {
+      expiresAt = options.expiresAt;
+    } else if (knobs.defaultExpirySeconds) {
+      expiresAt = new Date(Date.now() + knobs.defaultExpirySeconds * 1e3);
+    }
+    const record = await tx.create({
+      model: "api_key",
+      data: {
+        subjectType: subject.type,
+        subjectId: subject.id,
+        name: options.name,
+        keyHash: hash,
+        keyPrefix,
+        scopes: options.scopes ? JSON.stringify(options.scopes) : null,
+        expiresAt,
+        lastUsedAt: null,
+        isRevoked: false
+      }
+    });
+    return { key: raw, id: record.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 revokeKeyForSubject(db, subject, keyId) {
+  const record = await db.findOne({
+    model: "api_key",
+    where: [{ field: "id", operator: "=", value: keyId }]
+  });
+  if (!record || record.subjectType !== subject.type || record.subjectId !== subject.id) {
+    throw Errors.notFound("API key not found");
+  }
+  await db.update({
+    model: "api_key",
+    where: [{ field: "id", operator: "=", value: keyId }],
+    data: { isRevoked: true }
+  });
+}
+async function rotateKeyForSubject(db, subject, keyId, knobs) {
+  const record = await db.findOne({
+    model: "api_key",
+    where: [{ field: "id", operator: "=", value: keyId }]
+  });
+  if (!record || record.subjectType !== subject.type || record.subjectId !== subject.id) {
+    throw Errors.notFound("API key not found");
+  }
+  await db.update({
+    model: "api_key",
+    where: [{ field: "id", operator: "=", value: keyId }],
+    data: { isRevoked: true }
+  });
+  const { raw, hash, keyPrefix } = await generateApiKey(knobs.prefix);
+  const newRecord = await db.create({
+    model: "api_key",
+    data: {
+      subjectType: record.subjectType,
+      subjectId: record.subjectId,
+      name: record.name,
+      keyHash: hash,
+      keyPrefix,
+      scopes: record.scopes,
+      expiresAt: record.expiresAt,
+      lastUsedAt: null,
+      isRevoked: false
+    }
+  });
+  return { key: raw, id: newRecord.id };
+}
+async function resolveApiKey(db, rawKey) {
+  const hash = await hashToken(rawKey);
+  const record = await db.findOne({
+    model: "api_key",
+    where: [{ field: "keyHash", operator: "=", value: hash }]
+  });
+  if (!record || record.isRevoked)
+    return null;
+  if (record.expiresAt && record.expiresAt < /* @__PURE__ */ new Date())
+    return null;
+  if (record.subjectType === "USER") {
+    const user = await db.findOne({
+      model: "user",
+      where: [{ field: "id", operator: "=", value: record.subjectId }]
+    });
+    if (!user || !user.isActive)
+      return null;
+  } else if (record.subjectType === "SERVICE_ACCOUNT") {
+    const sa = await db.findOne({
+      model: "service_account",
+      where: [{ field: "id", operator: "=", value: record.subjectId }]
+    });
+    if (!sa || !sa.isActive)
+      return null;
+  }
+  await db.update({
+    model: "api_key",
+    where: [{ field: "id", operator: "=", value: record.id }],
+    data: { lastUsedAt: /* @__PURE__ */ new Date() }
+  });
+  return {
+    subject: { type: record.subjectType, id: record.subjectId },
+    scopes: record.scopes ? JSON.parse(record.scopes) : null
+  };
+}
+async function deleteAllKeysForSubject(db, subject) {
+  await db.delete({
+    model: "api_key",
+    where: subjectWhere(subject)
+  });
+}
+
+// src/plugins/api-key/index.ts
+var errorRef = ref("ErrorResponse");
+var apiKeySelfServiceRoutes = {
+  createKey: endpoint("POST", "/api-key/keys").summary("Create an API key").description("Create a new API key for the authenticated caller. The raw key is returned exactly once \u2014 it cannot be retrieved later.").tags("API Keys").security("bearer").body(obj({
+    name: str("Human-readable key label"),
+    scopes: arr(str(), "Optional permission scopes attached to the key"),
+    expiresAt: str("Optional expiry (ISO 8601 string)")
+  }, "name")).response(201, "Key created", obj({
+    key: str("Raw API key \u2014 shown exactly once, store it immediately"),
+    id: int("Database id of the key")
+  }, "key", "id")).response(400, "Bad request", errorRef).response(401, "Not authenticated", errorRef).handler("createKey").build(),
+  listKeys: endpoint("GET", "/api-key/keys").summary("List the caller's API keys").description("Return the active (non-revoked) API keys belonging to the authenticated caller. Raw keys and hashes are never returned.").tags("API Keys").security("bearer").response(200, "Keys", obj({
+    keys: arr(obj({
+      id: id("Database id"),
+      name: str("Key label"),
+      keyPrefix: str("First 12 characters of the key, for identification"),
+      scopes: arr(str()),
+      expiresAt: str("ISO 8601 expiry, if any"),
+      lastUsedAt: str("ISO 8601 timestamp of last successful resolve"),
+      createdAt: str("ISO 8601 creation timestamp")
+    }, "id", "name", "keyPrefix", "createdAt"))
+  }, "keys")).response(401, "Not authenticated", errorRef).handler("listKeys").build(),
+  revokeKey: endpoint("DELETE", "/api-key/keys/:id").summary("Revoke an API key").description("Revoke one of the authenticated caller's own API keys. Returns 404 if the id does not belong to the caller.").tags("API Keys").security("bearer").params(obj({ id: str("Key id") }, "id")).response(200, "Revoked", obj({ ok: bool() }, "ok")).response(401, "Not authenticated", errorRef).response(404, "Not found", errorRef).handler("revokeKey").build(),
+  rotateKey: endpoint("POST", "/api-key/keys/:id/rotate").summary("Rotate an API key").description("Revoke an existing key and issue a new one with the same name, scopes, and expiry. The new raw key is returned exactly once.").tags("API Keys").security("bearer").params(obj({ id: str("Key id to rotate") }, "id")).response(200, "Rotated", obj({
+    key: str("New raw API key \u2014 shown exactly once"),
+    id: int("Database id of the new key")
+  }, "key", "id")).response(401, "Not authenticated", errorRef).response(404, "Not found", errorRef).handler("rotateKey").build()
+};
+function apiKey(config = {}) {
+  const knobs = {
+    prefix: config.prefix ?? "fortress",
+    defaultExpirySeconds: config.defaultExpirySeconds ?? null,
+    maxKeysPerSubject: config.maxKeysPerSubject ?? 10
+  };
+  const mountRoutes = config.routes === true;
+  let observerRegistered = false;
+  return {
+    name: "api-key",
+    models: [{
+      name: "api_key",
+      fields: {
+        id: { type: "number", required: true },
+        subjectType: { type: "string", required: true },
+        subjectId: { type: "number", required: true },
+        name: { type: "string", required: true },
+        keyHash: { type: "string", required: true, unique: true },
+        keyPrefix: { type: "string", required: true },
+        scopes: { type: "string" },
+        expiresAt: { type: "date" },
+        lastUsedAt: { type: "date" },
+        isRevoked: { type: "boolean", required: true },
+        createdAt: { type: "date", required: true }
+      }
+    }],
+    ...mountRoutes ? { routes: apiKeySelfServiceRoutes } : {},
+    async resolvePrincipal(request, ctx) {
+      const auth = request.headers.get("authorization") ?? "";
+      const fromAuth = auth.startsWith("ApiKey ") ? auth.slice(7).trim() : null;
+      const fromHeader = !fromAuth ? request.headers.get("x-api-key") : null;
+      const key = fromAuth ?? fromHeader;
+      if (!key)
+        return null;
+      const resolved = await resolveApiKey(ctx.db, key);
+      if (!resolved)
+        return null;
+      return { subject: resolved.subject, scopes: resolved.scopes };
+    },
+    methods: (ctx) => {
+      if (!observerRegistered && ctx.iam) {
+        observerRegistered = true;
+        const cascade = async (event) => {
+          if (event.eventType === "SERVICE_ACCOUNT_DELETED" && event.targetId != null) {
+            await deleteAllKeysForSubject(ctx.db, {
+              type: "SERVICE_ACCOUNT",
+              id: event.targetId
+            });
+          }
+        };
+        ctx.iam.addIamObserver(cascade);
+      }
+      return {
+        async createKey(input, routeCtx) {
+          const subject = resolveCallerSubject(input, routeCtx);
+          const options = {
+            name: String(input.name ?? ""),
+            scopes: Array.isArray(input.scopes) ? input.scopes.map(String) : void 0,
+            expiresAt: coerceDate(input.expiresAt)
+          };
+          if (!options.name)
+            throw Errors.badRequest("name is required");
+          return createKeyForSubject(ctx.db, subject, options, knobs);
+        },
+        async listKeys(input, routeCtx) {
+          const subject = resolveCallerSubject(input, routeCtx);
+          return listKeysForSubject(ctx.db, subject);
+        },
+        async revokeKey(input, routeCtx) {
+          const subject = resolveCallerSubject(input, routeCtx);
+          const keyId = String(input.id ?? "");
+          if (!keyId)
+            throw Errors.badRequest("id is required");
+          await revokeKeyForSubject(ctx.db, subject, keyId);
+          return { ok: true };
+        },
+        async rotateKey(input, routeCtx) {
+          const subject = resolveCallerSubject(input, routeCtx);
+          const keyId = String(input.id ?? "");
+          if (!keyId)
+            throw Errors.badRequest("id is required");
+          return rotateKeyForSubject(ctx.db, subject, keyId, { prefix: knobs.prefix });
+        },
+        async resolveKey(rawKey) {
+          return resolveApiKey(ctx.db, rawKey);
+        }
+      };
+    }
+  };
+}
+function resolveCallerSubject(input, routeCtx) {
+  if (routeCtx) {
+    if (!routeCtx.subject)
+      throw Errors.unauthorized("Not authenticated");
+    if (routeCtx.scopes !== void 0)
+      throw Errors.forbidden("API keys cannot manage API keys");
+    return routeCtx.subject;
+  }
+  if (!input.subject)
+    throw Errors.badRequest("subject is required for programmatic calls");
+  return input.subject;
+}
+function coerceDate(value) {
+  if (value == null)
+    return void 0;
+  if (value instanceof Date)
+    return value;
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime()))
+    throw Errors.badRequest("expiresAt must be a valid date");
+  return parsed;
+}
+export {
+  apiKey
+};