@bajustone/fortress 1.0.0-rc.1

package/src/core/endpoint.ts

@@ -0,0 +1,149 @@
+import type { JSONSchema, Simplify } from './json-schema';
+import type { StandardSchemaV1 } from './standard-schema';
+
+/** HTTP method an {@link EndpointDefinition} can declare. */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+
+/** Authentication scheme required to call an endpoint. */
+export type SecurityRequirement = 'bearer' | 'basic' | 'apiKey' | 'none';
+
+/** A required IAM permission, expressed as a `(resource, action)` pair. */
+export interface EndpointPermission {
+  resource: string;
+  action: string;
+}
+
+/** OpenAPI / IAM metadata attached to an {@link EndpointDefinition}. */
+export interface EndpointMeta {
+  summary: string;
+  description?: string;
+  tags?: string[];
+  security?: SecurityRequirement[];
+  deprecated?: boolean;
+  /** IAM permission required to access this endpoint. Enforced by RBAC middleware. */
+  permission?: EndpointPermission;
+  /**
+   * What kind of bearer token this route accepts.
+   *
+   * - `'jwt'` (default) — the route expects a Fortress session JWT in
+   *   `Authorization: Bearer <jwt>` (or the cookie). The dispatcher runs
+   *   the plugin principal chain, JWT verification, and RBAC enforcement
+   *   automatically before invoking the handler.
+   * - `'oauth'` — the route's bearer is an OAuth 2.0 access token (or no
+   *   token at all, e.g. `/oauth/authorize`). The dispatcher skips its
+   *   auth pipeline entirely and the handler self-parses the bearer
+   *   (typical for `/oauth/userinfo`, `/oauth/token`, etc.). Body parsing
+   *   and validation are also skipped, since OAuth bodies are
+   *   `application/x-www-form-urlencoded` per RFC 6749.
+   *
+   * Routes that don't set this field default to `'jwt'`. Without this
+   * marker, the OAuth plugin's consent-flow endpoints
+   * (`/oauth/flows/:flowId{,/approve,/deny}`) — which are SPA-driven and
+   * require a Fortress JWT — used to be silently unauthenticated due to
+   * a path-based `startsWith('/oauth/')` short-circuit in the dispatcher,
+   * forcing every host app to ship a workaround shim. Setting
+   * `bearerKind: 'oauth'` only on the actual protocol routes lets the
+   * dispatcher honour `security: ['bearer']` everywhere else.
+   */
+  bearerKind?: 'jwt' | 'oauth';
+}
+
+/** Request input declarations for an endpoint — JSON Schemas for OpenAPI plus Standard Schemas for runtime validation. */
+export interface EndpointInput {
+  /** JSON Schema for OpenAPI spec generation. */
+  body?: JSONSchema;
+  query?: JSONSchema;
+  params?: JSONSchema;
+  /** Standard Schema references for runtime validation (set by endpoint builder). */
+  bodySchema?: StandardSchemaV1;
+  querySchema?: StandardSchemaV1;
+  paramsSchema?: StandardSchemaV1;
+}
+
+/** A single OpenAPI response definition (description plus optional JSON Schema). */
+export interface EndpointResponse {
+  description: string;
+  schema?: JSONSchema;
+}
+
+/**
+ * Declarative description of one HTTP endpoint.
+ *
+ * The four generic parameters are **phantom types** — they're populated by
+ * the fluent {@link EndpointBuilder} as schemas are declared via `.body()`,
+ * `.query()`, `.params()`, and `.response()`, and then extracted at the call
+ * site by the `InferEndpoint*` helpers (and by the typed `fortress.call.*`
+ * proxy). None of them exist at runtime.
+ *
+ * The defaults are `{}` (empty object), not `unknown`, so that the
+ * intersection-based `InferEndpointCallInput` collapses cleanly for
+ * endpoints that only declare one of the three input slots.
+ */
+export interface EndpointDefinition<
+  // eslint-disable-next-line ts/no-empty-object-type -- default must be {} so the input intersection collapses
+  TBody = {},
+  // eslint-disable-next-line ts/no-empty-object-type
+  TQuery = {},
+  // eslint-disable-next-line ts/no-empty-object-type
+  TParams = {},
+  // eslint-disable-next-line ts/no-empty-object-type
+  TResponses extends Record<number, unknown> = {},
+> {
+  method: HttpMethod;
+  path: string;
+  handler: string;
+  meta?: EndpointMeta;
+  input?: EndpointInput;
+  responses?: Record<number, EndpointResponse>;
+  /** Phantom — never present at runtime. Consumed by `InferEndpoint*` helpers. */
+  __types?: {
+    body: TBody;
+    query: TQuery;
+    params: TParams;
+    responses: TResponses;
+  };
+}
+
+// ── Endpoint type inference helpers ────────────────────────────────
+
+/** Extract the request-body type from an {@link EndpointDefinition}. */
+export type InferEndpointBody<E> = E extends EndpointDefinition<infer B, any, any, any> ? B : never;
+/** Extract the query-string type from an {@link EndpointDefinition}. */
+export type InferEndpointQuery<E> = E extends EndpointDefinition<any, infer Q, any, any> ? Q : never;
+/** Extract the path-params type from an {@link EndpointDefinition}. */
+export type InferEndpointParams<E> = E extends EndpointDefinition<any, any, infer P, any> ? P : never;
+/** Extract the full `Record<status, body>` response map from an {@link EndpointDefinition}. */
+export type InferEndpointResponses<E> = E extends EndpointDefinition<any, any, any, infer R> ? R : never;
+
+/**
+ * Extract the success-response body from an {@link EndpointDefinition}.
+ *
+ * Tries `200`, then `201`, then `204`, then falls back to `unknown`.
+ * This matches the behavior of the `fortress.call.*` proxy, which always
+ * resolves to the first successful status declared.
+ */
+export type InferEndpointSuccessResponse<E>
+  = InferEndpointResponses<E> extends infer R
+    ? R extends { 200: infer T } ? T
+      : R extends { 201: infer T } ? T
+        : R extends { 204: infer T } ? T
+          : unknown
+    : never;
+
+/**
+ * The flat input shape accepted by the typed `fortress.call.<handler>(input)`
+ * proxy — the intersection of body, query, and params. For endpoints that
+ * only declare one of the three, the other slots are `{}` and disappear from
+ * the intersection.
+ */
+export type InferEndpointCallInput<E> = Simplify<
+  InferEndpointBody<E> & InferEndpointQuery<E> & InferEndpointParams<E>
+>;
+
+/**
+ * Component schemas are reusable JSON Schema definitions
+ * that endpoints reference via $ref (e.g., '#/components/schemas/User').
+ */
+export interface ComponentSchemas {
+  [name: string]: JSONSchema;
+}

package/src/core/errors.ts

@@ -0,0 +1,199 @@
+/** Discriminated string union of every error code fortress can throw. Maps 1:1 to an HTTP status. */
+export type FortressErrorCode
+  = | 'UNAUTHORIZED'
+    | 'TOKEN_REUSE'
+    | 'SESSION_IDLE_TIMEOUT'
+    | 'SESSION_ABSOLUTE_TIMEOUT'
+    | 'FORBIDDEN'
+    | 'BAD_REQUEST'
+    | 'NOT_FOUND'
+    | 'CONFLICT'
+    | 'UNPROCESSABLE_ENTITY'
+    | 'RATE_LIMITED'
+    | 'DATABASE_ERROR'
+    | 'VALIDATION_ERROR'
+    | 'SERVICE_UNAVAILABLE';
+
+/**
+ * Machine-readable error codes defined by RFC 6749 §5.2 (token endpoint) and
+ * §4.1.2.1 (authorization endpoint). The OAuth plugin uses these as the
+ * `error` field in token-endpoint failure responses; the HTTP error mapper
+ * detects {@link FortressError.oauthError} and emits the
+ * `{ error, error_description }` shape required by the spec.
+ */
+export type OAuthErrorCode
+  = | 'invalid_request'
+    | 'invalid_client'
+    | 'invalid_grant'
+    | 'unauthorized_client'
+    | 'unsupported_grant_type'
+    | 'invalid_scope'
+    | 'access_denied'
+    | 'unsupported_response_type'
+    | 'server_error'
+    | 'temporarily_unavailable';
+
+/** The single error class fortress throws. Carries an error code, HTTP status, and structured details. */
+export class FortressError extends Error {
+  readonly code: FortressErrorCode;
+  readonly statusCode: number;
+  readonly retryAfter?: number;
+  readonly details?: unknown;
+  /** RFC 6749 §5.2 / §4.1.2.1 machine code. Set by `Errors.oauth()`. */
+  readonly oauthError?: OAuthErrorCode;
+  /** Human-readable description for the OAuth `error_description` field. */
+  readonly oauthDescription?: string;
+  /** Optional URI for the OAuth `error_uri` field (§5.2). */
+  readonly oauthErrorUri?: string;
+
+  constructor(
+    code: FortressErrorCode,
+    message: string,
+    statusCode: number,
+    options?: {
+      cause?: unknown;
+      retryAfter?: number;
+      details?: unknown;
+      oauthError?: OAuthErrorCode;
+      oauthDescription?: string;
+      oauthErrorUri?: string;
+    },
+  ) {
+    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(): { code: FortressErrorCode; message: string; statusCode: number; details?: unknown } {
+    return {
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      ...(this.details !== undefined && { details: this.details }),
+    };
+  }
+}
+
+/** Typed factory of {@link FortressError} constructors — one helper per error code. */
+export const Errors = {
+  unauthorized: (message = 'Unauthorized'): FortressError =>
+    new FortressError('UNAUTHORIZED', message, 401),
+  tokenReuse: (): FortressError =>
+    new FortressError('TOKEN_REUSE', 'Token reuse detected', 401),
+  sessionIdleTimeout: (): FortressError =>
+    new FortressError('SESSION_IDLE_TIMEOUT', 'Session idle timeout exceeded', 401),
+  sessionAbsoluteTimeout: (): FortressError =>
+    new FortressError('SESSION_ABSOLUTE_TIMEOUT', 'Session absolute timeout exceeded', 401),
+  forbidden: (message = 'Forbidden'): FortressError =>
+    new FortressError('FORBIDDEN', message, 403),
+  badRequest: (message = 'Bad request'): FortressError =>
+    new FortressError('BAD_REQUEST', message, 400),
+  notFound: (message = 'Not found'): FortressError =>
+    new FortressError('NOT_FOUND', message, 404),
+  conflict: (message = 'Conflict', options?: { cause?: unknown; details?: unknown }): FortressError =>
+    new FortressError('CONFLICT', message, 409, options),
+  unprocessable: (message = 'Unprocessable entity', options?: { cause?: unknown; details?: unknown }): FortressError =>
+    new FortressError('UNPROCESSABLE_ENTITY', message, 422, options),
+  rateLimited: (retryAfter: number): FortressError =>
+    new FortressError('RATE_LIMITED', 'Too many requests', 429, { retryAfter }),
+  database: (message = 'Database error', cause?: unknown): FortressError =>
+    new FortressError('DATABASE_ERROR', message, 500, { cause }),
+  serviceUnavailable: (message = 'Service unavailable', options?: { cause?: unknown; retryAfter?: number }): FortressError =>
+    new FortressError('SERVICE_UNAVAILABLE', message, 503, options),
+  validationError: (issues: Array<{ path?: unknown; message: string }>): FortressError =>
+    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: OAuthErrorCode,
+    description?: string,
+    options?: { status?: number; errorUri?: string; cause?: unknown },
+  ): FortressError => {
+    const status = options?.status ?? (error === 'invalid_client' ? 401 : 400);
+    const code: FortressErrorCode = 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: number, body: unknown): FortressError => {
+    const payload = (body && typeof body === 'object' ? body : {}) as {
+      code?: string;
+      message?: string;
+      details?: unknown;
+    };
+    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 });
+  },
+} as const;
+
+function isFortressErrorCode(code: string): code is FortressErrorCode {
+  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: number): FortressErrorCode {
+  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';
+}

package/src/core/fetcher-interop.test.ts

@@ -0,0 +1,106 @@
+/**
+ * Interop: authoring fortress endpoint schemas with `@bajustone/fetcher`'s own
+ * builder (re-exported at `@bajustone/fortress/fetcher`). Fetcher schemas are
+ * JSON Schema objects that implement Standard Schema V1, so they drop straight
+ * into `endpoint().body()/.query()/.params()/.response()`:
+ *   - runtime validation uses the fetcher schema's own compiled validator
+ *   - OpenAPI emission strips fetcher's internal `~`-prefixed keys, leaving
+ *     clean JSON Schema
+ *
+ * This locks that contract in so neither `extractJsonSchema` (detection) nor
+ * `cleanSchema` (OpenAPI serialization) can regress it.
+ */
+import type { StandardSchemaV1 } from './standard-schema';
+import { discriminatedUnion, email as femail, integer, literal, nullable, object, optional, string } from '@bajustone/fetcher/schema';
+import { describe, expect, it } from 'vitest';
+import { toOpenAPI } from './openapi';
+import { endpoint, extractJsonSchema, isStandardSchema } from './schema-builder';
+import { validateValue } from './validation';
+
+/** Recursively collect any object key beginning with `~` (fetcher internals). */
+function tildeKeys(value: unknown, acc: string[] = []): string[] {
+  if (Array.isArray(value)) {
+    for (const v of value)
+      tildeKeys(v, acc);
+  }
+  else if (value && typeof value === 'object') {
+    for (const [k, v] of Object.entries(value)) {
+      if (k.startsWith('~'))
+        acc.push(k);
+      tildeKeys(v, acc);
+    }
+  }
+  return acc;
+}
+
+const Body = object({
+  email: femail(),
+  name: string({ minLength: 1 }),
+  age: optional(integer()),
+  nick: nullable(string()),
+  kind: discriminatedUnion('t', {
+    a: object({ t: literal('a'), x: integer() }),
+    b: object({ t: literal('b'), y: string() }),
+  }),
+});
+
+describe('fetcher builder interop — endpoint authoring', () => {
+  it('a fetcher schema is a valid Standard Schema and JSON Schema', () => {
+    expect(isStandardSchema(Body)).toBe(true);
+    expect((Body as any).type).toBe('object');
+    // extractJsonSchema accepts the fetcher-shaped schema (no Zod-style adapter)
+    expect((extractJsonSchema(Body as any) as any).type).toBe('object');
+  });
+
+  it('validates request data via the fetcher schema validator', async () => {
+    const okValue = await validateValue(
+      Body as unknown as StandardSchemaV1,
+      { email: 'user@example.com', name: 'x', nick: null, kind: { t: 'a', x: 1 } },
+      'body',
+    );
+    expect(okValue).toMatchObject({ email: 'user@example.com', name: 'x' });
+
+    await expect(
+      validateValue(
+        Body as unknown as StandardSchemaV1,
+        { email: 'not-an-email', name: '', nick: 1, kind: { t: 'a', x: 'no' } },
+        'body',
+      ),
+    ).rejects.toMatchObject({ code: 'VALIDATION_ERROR', statusCode: 422 });
+  });
+
+  it('stores both JSON Schema (OpenAPI) and the validator on the endpoint', () => {
+    const ep = endpoint('POST', '/users')
+      .summary('Create user')
+      .body(Body as any)
+      .response(200, 'Created', object({ id: string() }) as any)
+      .handler('createUser')
+      .build();
+
+    expect(ep.input?.body?.type).toBe('object');
+    expect(typeof (ep.input?.bodySchema as any)?.['~standard'].validate).toBe('function');
+  });
+
+  it('emits clean OpenAPI — no fetcher ~ keys, correct shape', () => {
+    const ep = endpoint('POST', '/users')
+      .summary('Create user')
+      .body(Body as any)
+      .handler('createUser')
+      .build();
+
+    const spec = toOpenAPI([ep], { title: 't', version: '1' });
+    expect(tildeKeys(spec)).toEqual([]);
+
+    const schema = (spec as any).paths['/users'].post.requestBody.content['application/json'].schema;
+    // optional `age` is excluded from required; required keys present
+    expect(schema.required).toEqual(['email', 'name', 'nick', 'kind']);
+    // enforced email format surfaces as format + pattern
+    expect(schema.properties.email.format).toBe('email');
+    expect(typeof schema.properties.email.pattern).toBe('string');
+    // nullable → anyOf with a null branch (valid OpenAPI 3.1)
+    expect(schema.properties.nick.anyOf).toEqual([{ type: 'string' }, { type: 'null' }]);
+    // discriminatedUnion → oneOf + discriminator
+    expect(schema.properties.kind.oneOf).toHaveLength(2);
+    expect(schema.properties.kind.discriminator.propertyName).toBe('t');
+  });
+});