@bajustone/fortress 1.0.0-rc.1

package/src/core/standard-schema.ts

@@ -0,0 +1,56 @@
+/**
+ * Standard Schema V1 interfaces — inlined from the spec.
+ * No `@standard-schema/spec` dependency needed.
+ *
+ * @see https://standardschema.dev
+ * @see https://github.com/standard-schema/standard-schema
+ */
+
+// eslint-disable-next-line ts/no-namespace
+export declare namespace StandardSchemaV1 {
+  interface Props<Input = unknown, Output = Input> {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (
+      value: unknown,
+    ) => Result<Output> | Promise<Result<Output>>;
+    readonly types?: Types<Input, Output> | undefined;
+  }
+
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+
+  interface SuccessResult<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+  }
+
+  interface FailureResult {
+    readonly issues: ReadonlyArray<Issue>;
+  }
+
+  interface Issue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+
+  interface PathSegment {
+    readonly key: PropertyKey;
+  }
+
+  interface Types<Input = unknown, Output = Input> {
+    readonly input: Input;
+    readonly output: Output;
+  }
+
+  type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema['~standard']['types']
+  >['input'];
+
+  type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema['~standard']['types']
+  >['output'];
+}
+
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}

package/src/core/types.ts

@@ -0,0 +1,258 @@
+// --- Identity ---
+
+/**
+ * A fortress user record as returned by the database adapter.
+ *
+ * `id` is always a string at the fortress API surface. Adapters backed by
+ * numeric primary keys are responsible for stringifying on read and parsing
+ * on write at the adapter boundary — consumers of fortress never see the
+ * underlying representation. This matches the JWT/OIDC `sub` wire shape
+ * (RFC 7519 §4.1.2) and unblocks UUID/ULID/snowflake-keyed adapters.
+ */
+export interface FortressUser {
+  id: string;
+  email: string;
+  name: string;
+  isActive: boolean;
+  emailVerified?: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+// --- Auth ---
+
+/** JWT claims fortress signs into the access token, plus the optional impersonation actor (`act`) and per-deployment custom claims. */
+export interface TokenClaims {
+  /** Subject identifier — string per RFC 7519 §4.1.2. */
+  sub: string;
+  /** Subject kind — defaults to 'USER' on legacy tokens that do not carry the claim. */
+  subjectType: SubjectType;
+  name: string;
+  groups: string[];
+  iss: string;
+  /** Optional JWT audience, when configured for this deployment. */
+  aud?: string | string[];
+  iat: number;
+  exp: number;
+  act?: { sub: string; subjectType?: SubjectType }; // RFC 8693 actor claim for impersonation
+  customClaims?: Record<string, unknown>;
+}
+
+/** A short-lived access token paired with its longer-lived refresh token. */
+export interface AuthTokenPair {
+  accessToken: string;
+  refreshToken: string;
+}
+
+/** The credential method that completed authentication. Carried on a successful result. */
+export type AuthMethod = 'password' | 'refresh' | 'two-factor' | 'webauthn' | 'magic-link' | 'impersonation';
+
+/** Why a sign-in is pending an additional step before tokens are issued. */
+export type PendingReason = 'two-factor' | 'webauthn' | 'email-verification' | 'magic-link';
+
+/**
+ * The challenge a pending sign-in must satisfy before tokens are issued.
+ * `reason` tells the client which step to run; the single-use `continuationToken`
+ * is presented back to `auth.completePendingAuth` to finish the flow.
+ */
+export interface AuthChallenge {
+  reason: PendingReason;
+  continuationToken: string;
+}
+
+/** Successful sign-in / refresh result — both tokens are issued. */
+export interface AuthSuccess {
+  status: 'success';
+  user: FortressUser;
+  method: AuthMethod;
+  accessToken: string;
+  refreshToken: string;
+  pluginData?: Record<string, unknown>;
+}
+
+/** Impersonation sign-in result — only an access token is issued (refresh is suppressed for safety). */
+export interface AuthImpersonation {
+  status: 'impersonation';
+  user: FortressUser;
+  accessToken: string;
+  refreshToken: null;
+  pluginData?: Record<string, unknown>;
+}
+
+/** Pending sign-in result — the user must complete an additional step before tokens are issued. */
+export interface AuthPending {
+  status: 'pending';
+  user: FortressUser;
+  pending: AuthChallenge;
+  pluginData?: Record<string, unknown>;
+}
+
+/** Discriminated union of every possible auth flow outcome. */
+export type AuthResult = AuthSuccess | AuthImpersonation | AuthPending;
+
+/** Narrow an {@link AuthResult} to the successful (tokens-issued) variant. */
+export function isSuccess(result: AuthResult): result is AuthSuccess {
+  return result.status === 'success';
+}
+
+/** Narrow an {@link AuthResult} to the pending (additional-step-required) variant. */
+export function isPending(result: AuthResult): result is AuthPending {
+  return result.status === 'pending';
+}
+
+/** Narrow an {@link AuthResult} to the impersonation variant. */
+export function isImpersonation(result: AuthResult): result is AuthImpersonation {
+  return result.status === 'impersonation';
+}
+
+/**
+ * Assert an {@link AuthResult} is successful, throwing otherwise. Use when a
+ * caller has already ruled out the pending/impersonation variants and wants the
+ * token fields without a manual narrow.
+ */
+export function assertSuccess(result: AuthResult): asserts result is AuthSuccess {
+  if (result.status !== 'success')
+    throw new Error(`Expected a successful auth result, but got status '${result.status}'`);
+}
+
+/** Per-request metadata fortress threads through hooks for audit logging, lockout, and trusted-device tracking. */
+export interface RequestMeta {
+  ipAddress?: string;
+  userAgent?: string;
+  deviceName?: string;
+  /** Raw server-issued trusted-device secret from the host-owned cookie. */
+  trustedDeviceToken?: string;
+  /** Explicitly request enrollment of this browser/device after a successful factor. */
+  rememberDevice?: boolean;
+}
+
+/** A persisted refresh-token session as exposed to session-management UIs. */
+export interface SessionInfo {
+  id: string;
+  ipAddress: string | null;
+  userAgent: string | null;
+  deviceName: string | null;
+  createdAt: Date;
+  lastActiveAt: Date | null;
+}
+
+/** Input shape accepted by `fortress.createUser` and the admin user-creation endpoint. */
+export interface CreateUserInput {
+  email: string;
+  name: string;
+  password?: string;
+  isActive?: boolean;
+}
+
+// --- IAM ---
+
+/** The kind of subject a role or permission can be bound to. */
+export type SubjectType = 'USER' | 'GROUP' | 'SERVICE_ACCOUNT';
+
+/** A subject identity — a discriminated (type, id) pair used by IAM and the auth pipeline. */
+export interface Subject {
+  type: SubjectType;
+  id: string;
+}
+
+/** A persisted IAM permission — a (resource, action) pair with optional conditions and an allow/deny effect. */
+export interface Permission {
+  id: string;
+  resource: string;
+  action: string;
+  effect: 'ALLOW' | 'DENY';
+  conditions?: PermissionCondition[];
+  description?: string;
+}
+
+/** Input shape for creating a new {@link Permission}. */
+export interface PermissionInput {
+  resource: string;
+  action: string;
+  effect?: 'ALLOW' | 'DENY';
+  conditions?: PermissionCondition[];
+}
+
+/** Reference to a value resolved from the {@link PermissionContext} at evaluation time. */
+export interface ConditionRef {
+  ref: string;
+}
+
+/** A literal or {@link ConditionRef}-based value used by a {@link PermissionCondition}. */
+export type ConditionValue = string | string[] | ConditionRef | ConditionRef[];
+
+/** A single ABAC-style condition guarding a {@link Permission}. */
+export interface PermissionCondition {
+  field: string;
+  operator: 'eq' | 'neq' | 'in' | 'startsWith';
+  value: ConditionValue;
+}
+
+/** Context object passed into the permission evaluator at check time. */
+export interface PermissionContext {
+  resource?: Record<string, unknown>;
+  request?: Record<string, unknown>;
+  user?: Record<string, unknown>;
+  tenantId?: string;
+  /**
+   * Optional narrowing scopes from the credential used for this request
+   * (for example an API key). `null`/`undefined` means unscoped/full
+   * subject permissions; an empty array means no permissions.
+   */
+  credentialScopes?: string[] | null;
+}
+
+/** A persisted IAM role grouping a set of {@link Permission}s. */
+export interface Role {
+  id: string;
+  name: string;
+  description?: string | null;
+  isSystem?: boolean;
+}
+
+/** Binding of a {@link Role} to a subject (user, group, or service account), optionally scoped to a tenant. */
+export interface RoleBinding {
+  id: string;
+  roleId: string;
+  subjectType: SubjectType;
+  subjectId: string;
+  tenantId?: string | null;
+}
+
+/** The kind of identifier a user can sign in with. */
+export type LoginIdentifierType = 'email' | 'phone' | 'username';
+
+/** A persisted login identifier (e.g. email, phone, username) attached to a user. */
+export interface LoginIdentifier {
+  id: string;
+  userId: string;
+  type: LoginIdentifierType;
+  value: string;
+  /** Reserved for future multi-tenant support. Not yet stored in the database. */
+  tenantId?: string | null;
+}
+
+/** A persisted IAM group used to grant permissions to many users at once. */
+export interface Group {
+  id: string;
+  name: string;
+  description?: string;
+}
+
+/** A persisted IAM service account — a non-human principal that can hold roles and direct permissions. */
+export interface ServiceAccount {
+  id: string;
+  name: string;
+  displayName: string | null;
+  description: string | null;
+  isActive: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/** Input shape for creating a new {@link ServiceAccount}. `name` is the immutable machine identifier. */
+export interface CreateServiceAccountInput {
+  name: string;
+  displayName?: string;
+  description?: string;
+}

package/src/core/validation.test.ts

@@ -0,0 +1,195 @@
+import type { JSONSchema } from './json-schema';
+import { describe, expect, it } from 'vitest';
+import { FortressError } from './errors';
+import { iamEndpoints } from './iam/iam-endpoints';
+import { int, num, obj, str } from './schema-builder';
+import { coerceBySchema, validateRequest } from './validation';
+
+describe('coerceBySchema', () => {
+  it('coerces only lossless canonical decimal URL numerics', () => {
+    const schema = obj({ integer: int(), number: num() });
+    expect(coerceBySchema(schema, { integer: '-12', number: '0.5' })).toEqual({
+      integer: -12,
+      number: 0.5,
+    });
+    for (const value of [
+      '',
+      '0x10',
+      '1e3',
+      '+1',
+      '.5',
+      '01',
+      '1.0',
+      '-0',
+      '9007199254740992',
+      '0.10000000000000001',
+      'Infinity',
+    ]) {
+      expect(coerceBySchema(schema, { integer: value, number: value })).toEqual({
+        integer: value,
+        number: value,
+      });
+    }
+  });
+
+  it('leaves unsafe integers uncoerced so validation rejects them', async () => {
+    const paramsSchema = obj({ id: int() }, 'id');
+    const params = coerceBySchema(paramsSchema, { id: '9007199254740992' });
+
+    expect(params).toEqual({ id: '9007199254740992' });
+    await expect(
+      validateRequest({ params: paramsSchema, paramsSchema }, { params }),
+    ).rejects.toMatchObject({ code: 'VALIDATION_ERROR', statusCode: 422 });
+  });
+
+  it('coerces numeric enum and const properties without an explicit type', async () => {
+    const schema = {
+      type: 'object' as const,
+      properties: {
+        mode: { enum: [1, 2] },
+        version: { const: 3 },
+      },
+      required: ['mode', 'version'],
+    };
+    const params = coerceBySchema(schema, { mode: '2', version: '3' });
+
+    expect(params).toEqual({ mode: 2, version: 3 });
+    await expect(validateRequest({ params: schema }, { params })).resolves.toBeUndefined();
+  });
+});
+
+describe('validateRequest', () => {
+  it('no-op when input is undefined', async () => {
+    await expect(validateRequest(undefined, {})).resolves.toBeUndefined();
+  });
+
+  it('no-op when no schemas are set', async () => {
+    await expect(validateRequest({}, {})).resolves.toBeUndefined();
+  });
+
+  it('validates hand-authored JSON Schemas and aggregates locations', async () => {
+    const input = {
+      body: { type: 'object' as const, properties: { name: { type: 'string' as const } }, required: ['name'] },
+      query: { type: 'object' as const, properties: { page: { type: 'integer' as const } }, required: ['page'] },
+      params: { type: 'object' as const, properties: { id: { type: 'integer' as const } }, required: ['id'] },
+    };
+
+    try {
+      await validateRequest(input, { body: {}, query: {}, params: {} });
+      expect.unreachable();
+    }
+    catch (err) {
+      expect(err).toMatchObject({ code: 'VALIDATION_ERROR', statusCode: 422 });
+      const details = (err as FortressError).details as Array<{ location: string }>;
+      expect(details.map(issue => issue.location)).toEqual(['body', 'query', 'params']);
+    }
+  });
+
+  it('preserves definitions when validating a raw JSON Schema ref', async () => {
+    const body = {
+      $ref: '#/$defs/AdminBody',
+      $defs: {
+        AdminBody: {
+          type: 'object',
+          properties: { name: { type: 'string' } },
+          required: ['name'],
+        },
+      },
+    } as unknown as JSONSchema;
+
+    await expect(validateRequest({ body }, { body: { name: 'admin' } })).resolves.toBeUndefined();
+    await expect(
+      validateRequest({ body }, { body: {} }),
+    ).rejects.toMatchObject({ code: 'VALIDATION_ERROR', statusCode: 422 });
+  });
+
+  it('enforces component refs through a real IAM endpoint body', async () => {
+    const input = iamEndpoints.createRole.input;
+    await expect(validateRequest(input, {
+      body: { name: 'editor', permissions: [{ resource: 'posts', action: 'read' }] },
+    })).resolves.toBeUndefined();
+    await expect(validateRequest(input, {
+      body: { name: 'editor', permissions: [{ resource: 'posts' }] },
+    })).rejects.toMatchObject({ code: 'VALIDATION_ERROR', statusCode: 422 });
+  });
+
+  it('validates body via bodySchema', async () => {
+    const body = obj({ name: str() }, 'name');
+    const input = {
+      body: body as any,
+      bodySchema: body,
+    };
+
+    await expect(validateRequest(input, { body: { name: 'Alice' } })).resolves.toBeUndefined();
+
+    try {
+      await validateRequest(input, { body: {} });
+      expect.unreachable();
+    }
+    catch (err) {
+      expect(err).toBeInstanceOf(FortressError);
+      expect((err as FortressError).code).toBe('VALIDATION_ERROR');
+      expect((err as FortressError).statusCode).toBe(422);
+      expect((err as FortressError).details).toBeDefined();
+    }
+  });
+
+  it('validates query via querySchema', async () => {
+    const query = obj({ q: str() }, 'q');
+    const input = {
+      query: query as any,
+      querySchema: query,
+    };
+
+    await expect(validateRequest(input, { query: { q: 'hello' } })).resolves.toBeUndefined();
+
+    try {
+      await validateRequest(input, { query: {} });
+      expect.unreachable();
+    }
+    catch (err) {
+      expect((err as FortressError).code).toBe('VALIDATION_ERROR');
+    }
+  });
+
+  it('validates params via paramsSchema', async () => {
+    const params = obj({ id: int() }, 'id');
+    // Note: int() does not coerce strings 2014 a string id rejects.
+    const input = {
+      params: params as any,
+      paramsSchema: params,
+    };
+
+    await expect(validateRequest(input, { params: { id: 42 } })).resolves.toBeUndefined();
+
+    try {
+      await validateRequest(input, { params: {} });
+      expect.unreachable();
+    }
+    catch (err) {
+      expect((err as FortressError).code).toBe('VALIDATION_ERROR');
+    }
+  });
+
+  it('collects errors from multiple inputs', async () => {
+    const body = obj({ name: str() }, 'name');
+    const query = obj({ q: str() }, 'q');
+    const input = {
+      body: body as any,
+      bodySchema: body,
+      query: query as any,
+      querySchema: query,
+    };
+
+    try {
+      await validateRequest(input, { body: {}, query: {} });
+      expect.unreachable();
+    }
+    catch (err) {
+      const details = (err as FortressError).details as any[];
+      expect(details.length).toBe(2);
+      expect(details[0].location).toBe('body');
+      expect(details[1].location).toBe('query');
+    }
+  });
+});

package/src/core/validation.ts

@@ -0,0 +1,192 @@
+/**
+ * Runtime request validation using Standard Schema.
+ *
+ * Validates body/query/params against schemas stored in EndpointInput.
+ * Works with any Standard Schema provider (fortress, Zod, Valibot, ArkType).
+ */
+
+import type { EndpointInput } from './endpoint';
+import type { JSONSchema } from './json-schema';
+import type { StandardSchemaV1 } from './standard-schema';
+import { fromJSONSchema } from '@bajustone/fetcher/openapi';
+import { Errors } from './errors';
+
+// Keep URL numerics deliberately narrower than Number(): no exponent, sign, or
+// hexadecimal forms. The spelling must round-trip exactly so precision loss,
+// leading zeroes, and other non-canonical values remain validation failures.
+const DECIMAL_INTEGER_RE = /^-?\d+$/;
+const DECIMAL_NUMBER_RE = /^-?\d+(?:\.\d+)?$/;
+const rawSchemaValidators = new WeakMap<object, StandardSchemaV1>();
+
+function standardSchemaFor(schema: StandardSchemaV1 | JSONSchema): StandardSchemaV1 {
+  if ('~standard' in schema)
+    return schema as StandardSchemaV1;
+  let compiled = rawSchemaValidators.get(schema as object);
+  if (!compiled) {
+    compiled = fromJSONSchema(schema as object) as unknown as StandardSchemaV1;
+    rawSchemaValidators.set(schema as object, compiled);
+  }
+  return compiled;
+}
+
+/**
+ * Coerce URL-sourced query/params values to the types declared in a JSON
+ * Schema before runtime validation. HTTP path and query parameters arrive
+ * as strings from URL parsing, but endpoint schemas often declare them as
+ * `integer` / `number` / `boolean` for the purposes of OpenAPI docs and
+ * type inference. Without coercion, every `:id` / `?limit=10` would fail
+ * strict JSON Schema validation.
+ *
+ * Body data is _not_ run through this — JSON body values already arrive
+ * with their native types.
+ *
+ * Unknown or unparseable values pass through unchanged; the downstream
+ * validator produces the actual error if they don't match. Only the four
+ * primitive types (`integer`, `number`, `boolean`, `string`) are coerced
+ * — nested objects/arrays in query strings are out of scope.
+ */
+export function coerceBySchema(
+  schema: JSONSchema | undefined,
+  data: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (!schema || !data || schema.type !== 'object' || !schema.properties)
+    return data;
+
+  const out: Record<string, unknown> = { ...data };
+  for (const [key, propSchema] of Object.entries(schema.properties)) {
+    const value = out[key];
+    if (typeof value !== 'string')
+      continue;
+    const coerced = coerceScalar(propSchema as JSONSchema, value);
+    if (coerced !== undefined)
+      out[key] = coerced;
+  }
+  return out;
+}
+
+function coerceScalar(schema: JSONSchema, value: string): unknown {
+  // `enums()` and `literal()` intentionally omit `type`; infer numeric URL
+  // parameters from their numeric constraints so `/items?id=1` can satisfy
+  // `{ enum: [1, 2] }` and `{ const: 1 }`.
+  const type = schema.type ?? numericConstraintType(schema);
+  switch (type) {
+    case 'integer': {
+      if (!DECIMAL_INTEGER_RE.test(value))
+        return undefined;
+      const n = Number(value);
+      if (Number.isFinite(n) && Number.isSafeInteger(n) && String(n) === value)
+        return n;
+      return undefined;
+    }
+    case 'number': {
+      if (!DECIMAL_NUMBER_RE.test(value))
+        return undefined;
+      const n = Number(value);
+      if (Number.isFinite(n) && (!Number.isInteger(n) || Number.isSafeInteger(n)) && String(n) === value)
+        return n;
+      return undefined;
+    }
+    case 'boolean': {
+      if (value === 'true')
+        return true;
+      if (value === 'false')
+        return false;
+      return undefined;
+    }
+    default:
+      // Leave strings (and anything else) alone.
+      return undefined;
+  }
+}
+
+function numericConstraintType(schema: JSONSchema): 'integer' | 'number' | undefined {
+  if (typeof schema.const === 'number')
+    return Number.isInteger(schema.const) ? 'integer' : 'number';
+  if (schema.enum && schema.enum.length > 0 && schema.enum.every(value => typeof value === 'number'))
+    return schema.enum.every(value => Number.isInteger(value as number)) ? 'integer' : 'number';
+  return undefined;
+}
+
+/**
+ * Validate request data against endpoint input schemas.
+ * Throws FortressError('VALIDATION_ERROR') on failure.
+ *
+ * Uses `~standard.validate()` from whichever schema is attached
+ * (fortress built-in or external Standard Schema).
+ */
+export async function validateRequest(
+  input: EndpointInput | undefined,
+  data: { body?: unknown; query?: unknown; params?: unknown },
+): Promise<void> {
+  if (!input)
+    return;
+
+  const allIssues: Array<{ path?: unknown; message: string; location: string }> = [];
+
+  if (input.bodySchema || input.body) {
+    const issues = await validateSchema(input.bodySchema ?? input.body!, data.body, 'body');
+    allIssues.push(...issues);
+  }
+
+  if (input.querySchema || input.query) {
+    const issues = await validateSchema(input.querySchema ?? input.query!, data.query, 'query');
+    allIssues.push(...issues);
+  }
+
+  if (input.paramsSchema || input.params) {
+    const issues = await validateSchema(input.paramsSchema ?? input.params!, data.params, 'params');
+    allIssues.push(...issues);
+  }
+
+  if (allIssues.length > 0) {
+    throw Errors.validationError(allIssues);
+  }
+}
+
+async function validateSchema(
+  schema: StandardSchemaV1 | JSONSchema,
+  data: unknown,
+  location: string,
+): Promise<Array<{ path?: unknown; message: string; location: string }>> {
+  const result = await standardSchemaFor(schema)['~standard'].validate(data);
+  if (result.issues) {
+    return result.issues.map(issue => ({
+      path: issue.path,
+      message: issue.message,
+      location,
+    }));
+  }
+  return [];
+}
+
+/**
+ * Validate a single value against a Standard Schema and return the parsed
+ * value, or throw `Errors.validationError` on failure.
+ *
+ * Used by the per-handler request-extraction helpers (`vBody`/`vParam`/
+ * `vQuery`) in each framework adapter. Unlike {@link validateRequest}, which
+ * aggregates issues across body+query+params, this validates one location
+ * at a time — appropriate for per-handler call sites where a single helper
+ * call corresponds to a single piece of request data.
+ *
+ * The thrown `FortressError` is byte-identical to what `validateRequest`
+ * produces (HTTP 422, `VALIDATION_ERROR`, `details: issues[]`), so adapter
+ * error handlers format both consistently.
+ */
+export async function validateValue<T extends StandardSchemaV1>(
+  schema: T,
+  data: unknown,
+  location: 'body' | 'query' | 'params',
+): Promise<StandardSchemaV1.InferOutput<T>> {
+  const result = await schema['~standard'].validate(data);
+  if (result.issues) {
+    throw Errors.validationError(
+      result.issues.map(issue => ({
+        path: issue.path,
+        message: issue.message,
+        location,
+      })),
+    );
+  }
+  return result.value as StandardSchemaV1.InferOutput<T>;
+}