@bajustone/fortress 1.0.0-rc.1

package/src/plugins/api-key/core.ts

@@ -0,0 +1,336 @@
+/**
+ * Pure key operations for the api-key plugin.
+ *
+ * Extracted so both the api-key plugin (self-service) and the admin plugin
+ * (admin-over-users) can share one implementation without cross-plugin
+ * runtime coupling. Functions take a {@link DatabaseAdapter} plus args and
+ * throw {@link FortressError} via the existing `Errors` factory on failure.
+ *
+ * Keys are owned by a {@link Subject} — either a USER or a SERVICE_ACCOUNT
+ * (and extensible to future subject types). The storage schema uses a
+ * polymorphic `(subject_type, subject_id)` pair instead of a hard FK to
+ * `users.id`, mirroring `role_binding` / `direct_permission_binding`.
+ *
+ * @module
+ */
+
+import type { DatabaseAdapter } from '../../adapters/database';
+import type { FortressUser, ServiceAccount, Subject, SubjectType } from '../../core/types';
+import { hashToken } from '../../core/auth/refresh-token';
+import { Errors } from '../../core/errors';
+
+export interface ApiKeyInfo {
+  id: string;
+  name: string;
+  keyPrefix: string;
+  scopes: string[] | null;
+  expiresAt: Date | null;
+  lastUsedAt: Date | null;
+  createdAt: Date;
+}
+
+export interface ApiKeyRecord {
+  id: string;
+  subjectType: SubjectType;
+  subjectId: string;
+  name: string;
+  keyHash: string;
+  keyPrefix: string;
+  scopes: string | null;
+  expiresAt: Date | null;
+  lastUsedAt: Date | null;
+  isRevoked: boolean;
+  createdAt: Date;
+}
+
+export interface ApiKeyKnobs {
+  prefix: string;
+  defaultExpirySeconds: number | null;
+  maxKeysPerSubject: number;
+}
+
+export interface CreateKeyOptions {
+  name: string;
+  scopes?: string[];
+  expiresAt?: Date;
+}
+
+/** Generate a new random API key and its hash. */
+export async function generateApiKey(
+  prefix: string,
+): Promise<{ raw: string; hash: string; keyPrefix: string }> {
+  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);
+  // Include random material even when the configured textual prefix is long
+  // (the default `fortress_sk_` alone already occupies 12 characters).
+  const keyPrefix = `${prefix}_sk_${random.slice(0, 8)}`;
+  return { raw, hash, keyPrefix };
+}
+
+function toInfo(r: ApiKeyRecord): ApiKeyInfo {
+  return {
+    id: r.id,
+    name: r.name,
+    keyPrefix: r.keyPrefix,
+    scopes: r.scopes ? JSON.parse(r.scopes) as string[] : null,
+    expiresAt: r.expiresAt,
+    lastUsedAt: r.lastUsedAt,
+    createdAt: r.createdAt,
+  };
+}
+
+function subjectWhere(subject: Subject): Array<{ field: 'subjectType' | 'subjectId'; operator: '='; value: string | number }> {
+  return [
+    { field: 'subjectType', operator: '=', value: subject.type },
+    { field: 'subjectId', operator: '=', value: subject.id },
+  ];
+}
+
+/**
+ * Create a new key for a subject. Enforces `maxKeysPerSubject`. Caller-neutral —
+ * the admin plugin calls this on behalf of a target subject, self-service
+ * calls with the authenticated caller's subject.
+ */
+export async function createKeyForSubject(
+  db: DatabaseAdapter,
+  subject: Subject,
+  options: CreateKeyOptions,
+  knobs: ApiKeyKnobs,
+): Promise<{ key: string; id: string }> {
+  return db.transaction(async (tx) => {
+    // SQLite transactions take the writer lock; PostgreSQL needs an explicit
+    // subject-scoped advisory lock so count+insert is one atomic quota check
+    // across processes.
+    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: Date | null = null;
+    if (options.expiresAt) {
+      expiresAt = options.expiresAt;
+    }
+    else if (knobs.defaultExpirySeconds) {
+      expiresAt = new Date(Date.now() + knobs.defaultExpirySeconds * 1000);
+    }
+
+    const record = await tx.create<ApiKeyRecord>({
+      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 };
+  });
+}
+
+/** List non-revoked keys owned by a subject. Caller-neutral. */
+export async function listKeysForSubject(
+  db: DatabaseAdapter,
+  subject: Subject,
+): Promise<ApiKeyInfo[]> {
+  const records = await db.findMany<ApiKeyRecord>({
+    model: 'api_key',
+    where: [
+      ...subjectWhere(subject),
+      { field: 'isRevoked', operator: '=', value: false },
+    ],
+  });
+  return records.map(toInfo);
+}
+
+/**
+ * Revoke a key owned by the given subject. Throws `notFound` if the key is
+ * missing or belongs to a different subject — the ownership check enforces
+ * self-service semantics.
+ */
+export async function revokeKeyForSubject(
+  db: DatabaseAdapter,
+  subject: Subject,
+  keyId: string,
+): Promise<void> {
+  const record = await db.findOne<ApiKeyRecord>({
+    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 },
+  });
+}
+
+/**
+ * Rotate a key owned by the given subject — revokes the old one and issues
+ * a new one with the same name, scopes, and expiry. Same ownership check as
+ * {@link revokeKeyForSubject}.
+ */
+export async function rotateKeyForSubject(
+  db: DatabaseAdapter,
+  subject: Subject,
+  keyId: string,
+  knobs: { prefix: string },
+): Promise<{ key: string; id: string }> {
+  const record = await db.findOne<ApiKeyRecord>({
+    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<ApiKeyRecord>({
+    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 };
+}
+
+/**
+ * Resolve a raw API key to its owning subject + scopes. Returns `null` for
+ * unknown, revoked, expired, or inactive keys. Side-effect: updates
+ * `lastUsedAt` on successful resolution.
+ *
+ * USER and SERVICE_ACCOUNT owners are additionally checked for existence and
+ * `isActive` — this is the first line of defense before the permission
+ * resolver enforces the same gate in `internal-adapter.getSubjectPermissions`.
+ */
+export async function resolveApiKey(
+  db: DatabaseAdapter,
+  rawKey: string,
+): Promise<{ subject: Subject; scopes: string[] | null } | null> {
+  const hash = await hashToken(rawKey);
+  const record = await db.findOne<ApiKeyRecord>({
+    model: 'api_key',
+    where: [{ field: 'keyHash', operator: '=', value: hash }],
+  });
+
+  if (!record || record.isRevoked)
+    return null;
+  if (record.expiresAt && record.expiresAt < new Date())
+    return null;
+
+  // A credential cannot outlive or bypass deactivation of its owner.
+  if (record.subjectType === 'USER') {
+    const user = await db.findOne<FortressUser>({
+      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<ServiceAccount>({
+      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: new Date() },
+  });
+
+  return {
+    subject: { type: record.subjectType, id: record.subjectId },
+    scopes: record.scopes ? JSON.parse(record.scopes) as string[] : null,
+  };
+}
+
+// ── Admin-only helpers ───────────────────────────────────────────────
+
+/**
+ * Admin variant of {@link revokeKeyForSubject} — revokes any key by id
+ * without an ownership check. Use only behind an admin-permission gate.
+ */
+export async function revokeKeyAsAdmin(
+  db: DatabaseAdapter,
+  keyId: string,
+): Promise<void> {
+  const record = await db.findOne<ApiKeyRecord>({
+    model: 'api_key',
+    where: [{ field: 'id', operator: '=', value: keyId }],
+  });
+  if (!record)
+    throw Errors.notFound('API key not found');
+  await db.update({
+    model: 'api_key',
+    where: [{ field: 'id', operator: '=', value: keyId }],
+    data: { isRevoked: true },
+  });
+}
+
+/**
+ * Admin variant of {@link listKeysForSubject} — lists all keys for any
+ * subject without an ownership check. Used by the admin plugin's
+ * `adminListUserApiKeys` convenience helper.
+ */
+export async function listKeysForAnySubject(
+  db: DatabaseAdapter,
+  subject: Subject,
+): Promise<ApiKeyInfo[]> {
+  return listKeysForSubject(db, subject);
+}
+
+/**
+ * Hard-delete every api key owned by a subject. Used by the api-key plugin's
+ * IAM observer to cascade-delete keys when a service account is deleted.
+ */
+export async function deleteAllKeysForSubject(
+  db: DatabaseAdapter,
+  subject: Subject,
+): Promise<void> {
+  await db.delete({
+    model: 'api_key',
+    where: subjectWhere(subject),
+  });
+}

package/src/plugins/api-key/index.ts

@@ -0,0 +1,315 @@
+/**
+ * API key plugin for fortress.
+ *
+ * Issues scoped, hashed API keys for users and service accounts, with
+ * optional expiry, revocation, and per-key permission scopes. Authenticates
+ * incoming requests via `Authorization: ApiKey <key>` or `X-API-Key: <key>`
+ * headers and exposes management methods on the fortress instance.
+ *
+ * HTTP endpoints are opt-in: pass `apiKey({ routes: true })` to mount the
+ * self-service routes under `/api-key/keys/*`. The programmatic methods on
+ * `fortress.plugins['api-key']` are always available regardless of the flag.
+ *
+ * Keys are owned by a {@link Subject} — either a USER or a SERVICE_ACCOUNT.
+ * When a service account is deleted via core IAM, this plugin's IAM
+ * observer hard-deletes every key it owns.
+ *
+ * @module
+ */
+
+import type { IamEvent, IamEventListener } from '../../core/iam/iam-service';
+import type { FortressPlugin, PluginContext, PluginRouteContext } from '../../core/plugin';
+import type { Subject } from '../../core/types';
+import type { ApiKeyInfo, ApiKeyKnobs, CreateKeyOptions } from './core';
+import { Errors } from '../../core/errors';
+import { arr, bool, endpoint, id, int, obj, ref, str } from '../../core/schema-builder';
+import {
+  createKeyForSubject,
+  deleteAllKeysForSubject,
+  listKeysForSubject,
+  resolveApiKey,
+  revokeKeyForSubject,
+  rotateKeyForSubject,
+} from './core';
+
+export type { ApiKeyInfo, ApiKeyRecord } from './core';
+
+export interface ApiKeyConfig {
+  /** Prefix for generated keys (default: 'fortress') */
+  prefix?: string;
+  /** Default expiry in seconds. null = never expires (default: null) */
+  defaultExpirySeconds?: number | null;
+  /** Maximum active (non-revoked) keys per subject (default: 10) */
+  maxKeysPerSubject?: number;
+  /**
+   * Mount self-service HTTP routes under `/api-key/keys/*`. Default `false`.
+   * The programmatic methods on `fortress.plugins['api-key']` are always
+   * available; this flag only controls HTTP mounting.
+   */
+  routes?: boolean;
+}
+
+export interface ApiKeyMethods {
+  createKey: (
+    input: { subject?: Subject; name: string; scopes?: string[]; expiresAt?: Date | string },
+    routeCtx?: PluginRouteContext,
+  ) => Promise<{ key: string; id: string }>;
+  listKeys: (
+    input: { subject?: Subject },
+    routeCtx?: PluginRouteContext,
+  ) => Promise<ApiKeyInfo[]>;
+  revokeKey: (
+    input: { subject?: Subject; id: string },
+    routeCtx?: PluginRouteContext,
+  ) => Promise<{ ok: true }>;
+  rotateKey: (
+    input: { subject?: Subject; id: string },
+    routeCtx?: PluginRouteContext,
+  ) => Promise<{ key: string; id: string }>;
+  resolveKey: (
+    rawKey: string,
+  ) => Promise<{ subject: Subject; scopes: string[] | null } | null>;
+}
+
+// ── Routes ──────────────────────────────────────────────────────────
+
+const errorRef = ref('ErrorResponse');
+
+const 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 — 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 — 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 — 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(),
+} as const;
+
+// ── Plugin Factory ──────────────────────────────────────────────────
+
+/**
+ * API key plugin factory. Returns a {@link FortressPlugin} that issues
+ * scoped, hashed API keys, resolves them into request principals via the
+ * `Authorization: ApiKey`/`X-API-Key` headers, and exposes management
+ * methods on the fortress instance. Pass `{ routes: true }` to mount the
+ * self-service HTTP routes under `/api-key/keys/*`.
+ */
+export function apiKey(config: ApiKeyConfig = {}): FortressPlugin & { readonly name: 'api-key' } {
+  const knobs: ApiKeyKnobs = {
+    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: Request, ctx: PluginContext): Promise<{ subject: Subject; scopes?: string[] | null } | null> {
+      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: PluginContext) => {
+      // Register the IAM cascade observer exactly once per plugin instance.
+      // Done inside `methods` (rather than at factory time) because `ctx.iam`
+      // is not wired at factory construction — the Fortress boot order
+      // constructs services first, then calls `processPlugins` which invokes
+      // this `methods` factory with a fully-populated ctx.
+      if (!observerRegistered && ctx.iam) {
+        observerRegistered = true;
+        const cascade: IamEventListener = async (event: IamEvent) => {
+          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: { subject?: Subject; name: string; scopes?: string[]; expiresAt?: Date | string },
+          routeCtx?: PluginRouteContext,
+        ): Promise<{ key: string; id: string }> {
+          const subject = resolveCallerSubject(input, routeCtx);
+          const options: CreateKeyOptions = {
+            name: String(input.name ?? ''),
+            scopes: Array.isArray(input.scopes) ? input.scopes.map(String) : undefined,
+            expiresAt: coerceDate(input.expiresAt),
+          };
+          if (!options.name)
+            throw Errors.badRequest('name is required');
+          return createKeyForSubject(ctx.db, subject, options, knobs);
+        },
+
+        async listKeys(
+          input: { subject?: Subject },
+          routeCtx?: PluginRouteContext,
+        ): Promise<ApiKeyInfo[]> {
+          const subject = resolveCallerSubject(input, routeCtx);
+          return listKeysForSubject(ctx.db, subject);
+        },
+
+        async revokeKey(
+          input: { subject?: Subject; id: string },
+          routeCtx?: PluginRouteContext,
+        ): Promise<{ ok: true }> {
+          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: { subject?: Subject; id: string },
+          routeCtx?: PluginRouteContext,
+        ): Promise<{ key: string; id: string }> {
+          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: string,
+        ): Promise<{ subject: Subject; scopes: string[] | null } | null> {
+          return resolveApiKey(ctx.db, rawKey);
+        },
+      };
+    },
+  };
+}
+
+/**
+ * Resolve the caller's subject. Two call paths:
+ *
+ *  1. HTTP: the dispatcher passes `routeCtx` with the verified principal
+ *     (resolved from a JWT or an api-key `resolvePrincipal` pass). Use it
+ *     and ignore any `subject` in the body — the client doesn't get to pick
+ *     which subject a key is created for.
+ *  2. Programmatic (seed scripts, custom server code): no `routeCtx`, so
+ *     fall back to `input.subject`. These callers are trusted because they
+ *     already hold a reference to `fortress.plugins['api-key']`.
+ */
+function resolveCallerSubject(
+  input: { subject?: Subject },
+  routeCtx?: PluginRouteContext,
+): Subject {
+  if (routeCtx) {
+    if (!routeCtx.subject)
+      throw Errors.unauthorized('Not authenticated');
+    // Do not allow an API key credential to self-manage API keys. A scoped
+    // key could otherwise mint/rotate into a broader or unscoped key via the
+    // bearer-only self-service routes. Browser/JWT sessions have no
+    // credential scopes, so they remain allowed to manage their own keys.
+    if (routeCtx.scopes !== undefined)
+      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: Date | string | undefined): Date | undefined {
+  if (value == null)
+    return undefined;
+  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;
+}