@bajustone/fortress 1.0.0-rc.1

package/src/core/http/error-response.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest';
+import { Errors, FortressError } from '../errors';
+import { errorToResponse, withCookies } from './error-response';
+
+describe('errorToResponse', () => {
+  it('maps a FortressError to its declared status', async () => {
+    const res = errorToResponse(Errors.unauthorized('nope'));
+    expect(res.status).toBe(401);
+    expect(res.headers.get('content-type')).toBe('application/json');
+    const body = await res.json() as { code: string; message: string };
+    expect(body.code).toBe('UNAUTHORIZED');
+    expect(body.message).toBe('nope');
+  });
+
+  it('attaches Retry-After for RATE_LIMITED', () => {
+    const res = errorToResponse(Errors.rateLimited(42));
+    expect(res.status).toBe(429);
+    expect(res.headers.get('retry-after')).toBe('42');
+  });
+
+  it('omits Retry-After for non-rate-limited errors', () => {
+    const res = errorToResponse(Errors.forbidden());
+    expect(res.headers.get('retry-after')).toBeNull();
+  });
+
+  it('returns 500 INTERNAL_ERROR for unknown errors and does not leak the message', async () => {
+    const res = errorToResponse(new Error('something private'));
+    expect(res.status).toBe(500);
+    const body = await res.json() as { code: string; message: string };
+    expect(body.code).toBe('INTERNAL_ERROR');
+    expect(body.message).toBe('Internal server error');
+  });
+
+  it('handles validation errors (issue array)', async () => {
+    const err = Errors.validationError([{ message: 'required', path: ['email'] }]);
+    expect(err).toBeInstanceOf(FortressError);
+    const res = errorToResponse(err);
+    expect(res.status).toBe(422);
+    const body = await res.json() as { code: string; details: unknown };
+    expect(body.code).toBe('VALIDATION_ERROR');
+    expect(body.details).toBeDefined();
+  });
+});
+
+describe('withCookies', () => {
+  it('returns the same response when no cookies given', () => {
+    const r = new Response('hi', { status: 200 });
+    expect(withCookies(r, [])).toBe(r);
+  });
+
+  it('appends multiple Set-Cookie headers (not overwriting)', () => {
+    const r = new Response('{}', {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+    const out = withCookies(r, ['a=1; Path=/', 'b=2; Path=/']);
+    const setCookies = out.headers.getSetCookie();
+    expect(setCookies).toContain('a=1; Path=/');
+    expect(setCookies).toContain('b=2; Path=/');
+    expect(out.headers.get('content-type')).toBe('application/json');
+  });
+
+  it('preserves status and statusText', () => {
+    const r = new Response('x', { status: 201, statusText: 'Created' });
+    const out = withCookies(r, ['a=1']);
+    expect(out.status).toBe(201);
+    expect(out.statusText).toBe('Created');
+  });
+});

package/src/core/http/error-response.ts

@@ -0,0 +1,93 @@
+/**
+ * Map any thrown error to a web-standard `Response`.
+ *
+ * Knows about {@link FortressError} (typed status + retry-after handling)
+ * and falls back to a sanitized 500 for everything else. Used by
+ * `fortress.handleRequest` and re-exportable by adapters.
+ */
+
+import type { FortressLogger } from '../observability/logger';
+import { FortressError } from '../errors';
+
+/** JSON shape of an internal/unknown error response. */
+interface InternalErrorBody {
+  code: 'INTERNAL_ERROR';
+  message: 'Internal server error';
+  statusCode: 500;
+}
+
+/**
+ * Convert any caught error into a JSON `Response`. {@link FortressError}
+ * instances are mapped to their declared status code, with `Retry-After`
+ * set for `RATE_LIMITED`. Unknown errors return a sanitized 500 with no
+ * stack trace; the original error is routed to the caller-supplied
+ * {@link FortressLogger} at `error` level.
+ */
+export function errorToResponse(err: unknown, logger?: FortressLogger): Response {
+  if (err instanceof FortressError) {
+    const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+    if (err.code === 'RATE_LIMITED' && err.retryAfter !== undefined) {
+      headers['Retry-After'] = String(err.retryAfter);
+    }
+    // RFC 6749 §5.2: token-endpoint failures MUST use the
+    // `{ error, error_description, error_uri? }` shape with a
+    // machine-readable `error` code. Detect it via FortressError.oauthError
+    // and emit the spec body in place of the default fortress envelope.
+    if (err.oauthError) {
+      const body: Record<string, unknown> = { error: err.oauthError };
+      if (err.oauthDescription)
+        body.error_description = err.oauthDescription;
+      if (err.oauthErrorUri)
+        body.error_uri = err.oauthErrorUri;
+      // For 401s on the token endpoint the spec also recommends a
+      // `WWW-Authenticate: Basic realm="..."` header when the client used
+      // HTTP Basic; clients ignore it in practice and we don't track the
+      // auth scheme here, so omit it.
+      return new Response(JSON.stringify(body), {
+        status: err.statusCode,
+        headers,
+      });
+    }
+    return new Response(JSON.stringify(err.toJSON()), {
+      status: err.statusCode,
+      headers,
+    });
+  }
+
+  logger?.error(
+    { err, message: err instanceof Error ? err.message : 'Unknown error' },
+    'unhandled error in fortress.handleRequest',
+  );
+  const body: InternalErrorBody = {
+    code: 'INTERNAL_ERROR',
+    message: 'Internal server error',
+    statusCode: 500,
+  };
+  return new Response(JSON.stringify(body), {
+    status: 500,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+/**
+ * Append `Set-Cookie` headers to an existing `Response`. The web-standard
+ * `Headers.set` only keeps the last `set-cookie`, so multiple cookies must
+ * use `append`. This helper centralizes that quirk for adapters.
+ *
+ * Returns a *new* `Response` with the cookies merged in. The original is
+ * not mutated (its body is teed via `.clone()` semantics through the
+ * constructor).
+ */
+export function withCookies(response: Response, setCookies: string[]): Response {
+  if (setCookies.length === 0)
+    return response;
+  const headers = new Headers(response.headers);
+  for (const cookie of setCookies) {
+    headers.append('set-cookie', cookie);
+  }
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}

package/src/core/http/fortress-rbac.test.ts

@@ -0,0 +1,43 @@
+import type { EndpointDefinition } from '../endpoint';
+import { describe, expect, it, vi } from 'vitest';
+import { enforceFortressPermission } from './fortress-rbac';
+
+function endpoint(security: NonNullable<EndpointDefinition['meta']>['security']): EndpointDefinition {
+  return {
+    method: 'GET',
+    path: '/billing',
+    handler: 'billing',
+    input: {},
+    responses: {},
+    meta: {
+      summary: 'Billing',
+      security,
+      permission: { resource: 'billing', action: 'read' },
+    },
+  };
+}
+
+describe('enforceFortressPermission', () => {
+  it('enforces permission before basic transport metadata', async () => {
+    const checkPermission = vi.fn(async () => false);
+    await expect(enforceFortressPermission(
+      endpoint(['basic']),
+      { type: 'USER', id: '1' },
+      { checkPermission },
+    )).rejects.toMatchObject({ code: 'FORBIDDEN' });
+    expect(checkPermission).toHaveBeenCalledWith(
+      { type: 'USER', id: '1' },
+      'billing',
+      'read',
+      undefined,
+    );
+  });
+
+  it('requires a subject for api-key permission routes', async () => {
+    await expect(enforceFortressPermission(
+      endpoint(['apiKey']),
+      undefined,
+      { checkPermission: async () => true },
+    )).rejects.toMatchObject({ code: 'UNAUTHORIZED' });
+  });
+});

package/src/core/http/fortress-rbac.ts

@@ -0,0 +1,127 @@
+/**
+ * Default-deny RBAC for fortress-managed routes.
+ *
+ * Run by `fortress.handleRequest` *after* an endpoint has been matched. Uses
+ * the endpoint's `meta.security` and `meta.permission` declarations to
+ * decide whether the caller is allowed through:
+ *
+ * - `security: 'none'` or `security: 'basic'` → public, allow.
+ * - `meta.permission` set → require auth + IAM `checkPermission`.
+ * - `security: 'bearer'` (no permission) → require auth, no IAM check.
+ * - Anything else → deny (security-first default).
+ *
+ * Adapter-side route maps (Hono/Express user-route protection) live in
+ * each adapter — this module only handles fortress's own routes.
+ */
+
+import type { EndpointDefinition } from '../endpoint';
+import type { FortressPlugin } from '../plugin';
+import type { Subject } from '../types';
+import { Errors } from '../errors';
+
+const FORTRESS_CORE_PREFIXES = ['/iam/'];
+const FORTRESS_AUTH_PROTECTED = ['/auth/impersonate', '/auth/users'];
+const PLUGIN_PREFIX_REGEX = /^(\/[^/]+\/)/;
+
+/**
+ * Compute the unique top-level path prefixes (e.g. `/oauth/`) used by all
+ * registered plugin routes. Adapters call this once at startup to feed
+ * {@link isFortressPath}.
+ */
+export function getPluginPathPrefixes(plugins: readonly FortressPlugin[]): string[] {
+  const prefixes = new Set<string>();
+  for (const plugin of plugins) {
+    if (!plugin.routes)
+      continue;
+    for (const route of Object.values(plugin.routes)) {
+      const match = PLUGIN_PREFIX_REGEX.exec(route.path);
+      if (match)
+        prefixes.add(match[1]);
+    }
+  }
+  return [...prefixes];
+}
+
+/**
+ * Check whether a path is owned by fortress (core IAM, sensitive auth, or
+ * any plugin-registered prefix). Fortress-owned paths are subject to
+ * default-deny when no permission mapping resolves.
+ */
+export function isFortressPath(
+  path: string,
+  pluginPathPrefixes: readonly string[],
+): boolean {
+  if (FORTRESS_CORE_PREFIXES.some(p => path.startsWith(p)))
+    return true;
+  if (FORTRESS_AUTH_PROTECTED.some(p => path === p || path.startsWith(`${p}/`)))
+    return true;
+  if (pluginPathPrefixes.some(p => path.startsWith(p)))
+    return true;
+  return false;
+}
+
+/**
+ * Per-call dependencies for {@link enforceFortressPermission}.
+ */
+export interface PermissionEnforcement {
+  /** IAM check, typically `fortress.iam.checkPermission`. */
+  checkPermission: (
+    subject: Subject,
+    resource: string,
+    action: string,
+    scopes?: string[] | null,
+  ) => Promise<boolean>;
+}
+
+/**
+ * Enforce fortress's default-deny policy for an already-matched endpoint.
+ *
+ * - Public endpoints (`security: 'none'` / `'basic'`) pass through.
+ * - Endpoints with `meta.permission` require an authenticated subject and a
+ *   passing `checkPermission` call — otherwise throws `UNAUTHORIZED` /
+ *   `FORBIDDEN`.
+ * - Bearer-only endpoints require an authenticated subject but skip IAM.
+ * - Endpoints with no security metadata are denied.
+ *
+ * The caller (typically `fortress.handleRequest`) is responsible for first
+ * resolving the request principal (either via a plugin's `resolvePrincipal`
+ * or the JWT fallback) and supplying the resulting `subject`.
+ */
+export async function enforceFortressPermission(
+  endpoint: EndpointDefinition,
+  subject: Subject | undefined,
+  enforcement: PermissionEnforcement,
+  scopes?: string[] | null,
+): Promise<void> {
+  const security = endpoint.meta?.security;
+
+  // Explicit IAM permission requirements always win over transport metadata.
+  // A route cannot become public merely because it also accepts Basic auth.
+  if (endpoint.meta?.permission) {
+    if (!subject)
+      throw Errors.unauthorized('Not authenticated');
+    const allowed = await enforcement.checkPermission(
+      subject,
+      endpoint.meta.permission.resource,
+      endpoint.meta.permission.action,
+      scopes,
+    );
+    if (!allowed)
+      throw Errors.forbidden('Insufficient permissions');
+    return;
+  }
+
+  // Public/self-authenticated routes without an IAM requirement.
+  if (security?.includes('none') || security?.includes('basic'))
+    return;
+
+  // Bearer-only routes — auth required, no IAM check
+  if (security?.includes('bearer')) {
+    if (!subject)
+      throw Errors.unauthorized('Not authenticated');
+    return;
+  }
+
+  // No security metadata at all → default deny
+  throw Errors.forbidden('No permission mapping for this route');
+}