@bajustone/fortress 1.0.0-rc.1

package/src/hono/validated.test.ts

@@ -0,0 +1,123 @@
+import type { InferOutput } from './validated';
+import { Hono } from 'hono';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { obj, str } from '../core/schema-builder';
+import { createErrorHandler } from './middleware/error-handler';
+import { vBody, vParam, vQuery } from './validated';
+
+const CreateUserBody = obj({ name: str(), email: str() }, 'name', 'email');
+const IdParam = obj({ id: str('User ID') }, 'id');
+const SearchQuery = obj({ q: str('Search query'), page: str() }, 'q');
+
+function createApp(): Hono {
+  const app = new Hono();
+  app.onError(createErrorHandler());
+
+  app.post('/users', async (c) => {
+    const body = await vBody(c, CreateUserBody);
+    return c.json(body);
+  });
+
+  app.get('/users/:id', async (c) => {
+    const params = await vParam(c, IdParam);
+    return c.json(params);
+  });
+
+  app.get('/search', async (c) => {
+    const query = await vQuery(c, SearchQuery);
+    return c.json(query);
+  });
+
+  return app;
+}
+
+describe('vBody', () => {
+  it('returns parsed JSON body when valid', async () => {
+    const app = createApp();
+    const res = await app.request('/users', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'Alice', email: 'alice@test.com' }),
+    });
+    expect(res.status).toBe(200);
+    const data = await res.json();
+    expect(data).toEqual({ name: 'Alice', email: 'alice@test.com' });
+  });
+
+  it('returns 422 VALIDATION_ERROR when body is missing required fields', async () => {
+    const app = createApp();
+    const res = await app.request('/users', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'Alice' }),
+    });
+    expect(res.status).toBe(422);
+    const data = await res.json();
+    expect(data.code).toBe('VALIDATION_ERROR');
+    expect(Array.isArray(data.details)).toBe(true);
+    expect(data.details.some((i: { location: string }) => i.location === 'body')).toBe(true);
+  });
+
+  it('returns 422 when body is not parseable JSON', async () => {
+    const app = createApp();
+    const res = await app.request('/users', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: 'not json',
+    });
+    expect(res.status).toBe(422);
+    const data = await res.json();
+    expect(data.code).toBe('VALIDATION_ERROR');
+  });
+});
+
+describe('vParam', () => {
+  it('returns route params when valid', async () => {
+    const app = createApp();
+    const res = await app.request('/users/42');
+    expect(res.status).toBe(200);
+    const data = await res.json();
+    expect(data.id).toBe('42');
+  });
+});
+
+describe('vQuery', () => {
+  it('returns query parameters when valid', async () => {
+    const app = createApp();
+    const res = await app.request('/search?q=hello');
+    expect(res.status).toBe(200);
+    const data = await res.json();
+    expect(data.q).toBe('hello');
+  });
+
+  it('returns 422 when required query field is missing', async () => {
+    const app = createApp();
+    const res = await app.request('/search');
+    expect(res.status).toBe(422);
+    const data = await res.json();
+    expect(data.code).toBe('VALIDATION_ERROR');
+    expect(data.details.some((i: { location: string }) => i.location === 'query')).toBe(true);
+  });
+});
+
+describe('type inference', () => {
+  it('infers vBody return type from schema', () => {
+    const fn = (c: any) => vBody(c, CreateUserBody);
+    expectTypeOf(fn).returns.resolves.toEqualTypeOf<{ name: string; email: string }>();
+  });
+
+  it('infers vParam return type from schema', () => {
+    const fn = (c: any) => vParam(c, IdParam);
+    expectTypeOf(fn).returns.resolves.toEqualTypeOf<{ id: string }>();
+  });
+
+  it('infers vQuery return type from schema', () => {
+    const fn = (c: any) => vQuery(c, SearchQuery);
+    expectTypeOf(fn).returns.resolves.toEqualTypeOf<{ q: string; page?: string }>();
+  });
+
+  it('exports InferOutput utility type', () => {
+    type Expected = InferOutput<typeof CreateUserBody>;
+    expectTypeOf<Expected>().toEqualTypeOf<{ name: string; email: string }>();
+  });
+});

package/src/hono/validated.ts

@@ -0,0 +1,62 @@
+/**
+ * Typed extraction-and-validation helpers for Hono handlers.
+ *
+ * These helpers extract request data (body, params, query) **and validate
+ * it at runtime** against the supplied Standard Schema. On success they
+ * return the parsed value with full TypeScript inference; on failure they
+ * throw `FortressError('VALIDATION_ERROR', 422)` — the same shape every
+ * fortress-managed endpoint produces — so the existing Hono error handler
+ * formats it identically.
+ *
+ * Works with any Standard Schema V1 library: Zod, Valibot, ArkType, or
+ * fortress's built-in schema builders.
+ *
+ * @example
+ * ```ts
+ * import { vBody, vParam, vQuery } from '@bajustone/fortress/hono';
+ *
+ * app.post('/users/:id', async (c) => {
+ *   const body     = await vBody(c, CreateUserBody);
+ *   const { id }   = await vParam(c, IdParam);
+ *   const { page } = await vQuery(c, PaginationQuery);
+ *   // ...
+ * });
+ * ```
+ *
+ * Validation runs per call, so the first failing helper throws and any
+ * downstream helpers in the same handler do not run. If you need to
+ * aggregate body+query+params issues into a single response, use the
+ * framework-agnostic `validateRequest` from `@bajustone/fortress` instead.
+ */
+
+import type { Context } from 'hono';
+import type { StandardSchemaV1 } from '../core/standard-schema';
+import { validateValue } from '../core/validation';
+
+/** Infer the output type of a Standard Schema V1 schema. */
+export type InferOutput<T extends StandardSchemaV1> = StandardSchemaV1.InferOutput<T>;
+
+/**
+ * Extract and validate the request body. Returns the parsed value typed as
+ * `InferOutput<T>`, or throws `FortressError('VALIDATION_ERROR', 422)`.
+ */
+export async function vBody<T extends StandardSchemaV1>(c: Context, schema: T): Promise<InferOutput<T>> {
+  const body = await c.req.json().catch(() => undefined);
+  return validateValue(schema, body, 'body');
+}
+
+/**
+ * Extract and validate route parameters. Returns the parsed value typed as
+ * `InferOutput<T>`, or throws `FortressError('VALIDATION_ERROR', 422)`.
+ */
+export async function vParam<T extends StandardSchemaV1>(c: Context, schema: T): Promise<InferOutput<T>> {
+  return validateValue(schema, c.req.param(), 'params');
+}
+
+/**
+ * Extract and validate query parameters. Returns the parsed value typed as
+ * `InferOutput<T>`, or throws `FortressError('VALIDATION_ERROR', 422)`.
+ */
+export async function vQuery<T extends StandardSchemaV1>(c: Context, schema: T): Promise<InferOutput<T>> {
+  return validateValue(schema, c.req.query(), 'query');
+}

package/src/index.ts

@@ -0,0 +1,309 @@
+/**
+ * Fortress — framework-agnostic authentication and authorization for TypeScript.
+ *
+ * The main entrypoint exposes the {@link createFortress} factory, plugin and
+ * adapter interfaces, the schema builder DSL, and every public type. Combine
+ * with one of the framework adapters (`@bajustone/fortress/hono`,
+ * `@bajustone/fortress/express`, `@bajustone/fortress/sveltekit`) and a
+ * database adapter (`@bajustone/fortress/drizzle`,
+ * `@bajustone/fortress/testing`).
+ *
+ * @example
+ * ```ts
+ * import { createFortress } from '@bajustone/fortress';
+ * import { createDrizzleAdapter } from '@bajustone/fortress/drizzle';
+ *
+ * const fortress = createFortress({
+ *   database: createDrizzleAdapter(db, { dialect: 'pg' }),
+ *   jwt: { key: process.env.JWT_SECRET! },
+ * });
+ *
+ * const result = await fortress.auth.login('a@b.co', 'secret');
+ * ```
+ *
+ * @module
+ */
+
+/** Generic CRUD database adapter interface — implement to back fortress with any datastore. */
+export type { DatabaseAdapter } from './adapters/database';
+
+/** Where-clause primitives used by adapters and `scopeRules` to express filters. */
+export type { CoreOperator, ScopeRule, WhereClause } from './adapters/database/types';
+
+/** Pre-built endpoint definitions, schemas, and stable JSON wire types for core auth routes. */
+export type {
+  AuthChallengeWire,
+  AuthImpersonationWire,
+  AuthPendingWire,
+  AuthResultWire,
+  AuthSuccessWire,
+} from './core/auth/auth-endpoints';
+export { authComponentSchemas, authEndpoints } from './core/auth/auth-endpoints';
+
+/** Auth lifecycle event + listener types, emitted via `fortress.auth.addAuthObserver`. */
+export type { AuthEvent, AuthEventListener } from './core/auth/auth-service';
+
+/** Public JWT key-material type used by FortressConfig. */
+export type { JwtKeyMaterial } from './core/auth/jwt';
+
+export type {
+  PasswordBreachCheckOptions,
+  PasswordBreachDegradedEvent,
+  PasswordBreachFailureMode,
+  PasswordPolicyConfig,
+  PasswordPolicyObserver,
+} from './core/auth/password-policy';
+/** Top-level fortress configuration and pluggable password-hasher contract. */
+export type { FortressConfig, PasswordHasher, SessionConfig } from './core/config';
+/**
+ * Endpoint definition primitives — declarative `EndpointDefinition` objects
+ * carrying request/response schemas, OpenAPI metadata, and HTTP method info
+ * so framework adapters can mount routes without per-framework duplication.
+ *
+ * Plus the `InferEndpoint*` helpers that extract body/query/params/response
+ * types from an endpoint's generic parameters — the foundation of the typed
+ * `fortress.call.*` in-process client.
+ */
+export type {
+  ComponentSchemas,
+  EndpointDefinition,
+  EndpointInput,
+  EndpointMeta,
+  EndpointResponse,
+  HttpMethod,
+  InferEndpointBody,
+  InferEndpointCallInput,
+  InferEndpointParams,
+  InferEndpointQuery,
+  InferEndpointResponses,
+  InferEndpointSuccessResponse,
+  SecurityRequirement,
+} from './core/endpoint';
+/** Single error class plus the typed factory used throughout fortress. */
+export { Errors, FortressError } from './core/errors';
+/** Discriminated string unions for Fortress and OAuth errors. */
+export type { FortressErrorCode, OAuthErrorCode } from './core/errors';
+
+/** Factory that builds a configured fortress instance and the helper for type-safe plugin method access. */
+export { createFortress, getPluginMethods } from './core/fortress';
+
+/** The fortress instance type returned by {@link createFortress}, plus the typed call-map helper. */
+export type { Fortress, FortressToOpenAPIOptions, MigrateOptions, MigrateResult, TypedCall } from './core/fortress';
+
+/** Typed in-process client builder and per-call options. */
+export { buildCall } from './core/http/call';
+
+export type { CallOptions } from './core/http/call';
+
+/** Cross-adapter context passed to plugin middleware under core, Hono, and Express. */
+export type { PluginRequestContext } from './core/http/plugin-middleware';
+export { describeProtectedTarget, protect, resolveProtectedEndpoint } from './core/http/protect';
+export type { ProtectedRouteContext, ProtectedRouteHandler, ProtectedRouteTarget, ProtectOptions } from './core/http/protect';
+
+/** Permission debugging helper — "why does subject X have / not have permission Y?". */
+export { explainPermission } from './core/iam/explain';
+export type { PermissionExplanation, PermissionExplanationSource } from './core/iam/explain';
+/** Pre-built endpoint definitions and component schemas for the core IAM routes. */
+export { iamComponentSchemas, iamEndpoints } from './core/iam/iam-endpoints';
+
+/** IAM mutation and permission-check observer contracts. */
+export type {
+  IamEvent,
+  IamEventListener,
+  IamService,
+  PermissionCheckEvent,
+  PermissionCheckListener,
+} from './core/iam/iam-service';
+/** Manifest-driven RBAC permission seeding. See {@link Fortress.syncPermissionsFromManifest}. */
+export { runPermissionSync } from './core/iam/permission-sync';
+export type { PermissionSyncOptions, PermissionSyncResult } from './core/iam/permission-sync';
+export { parseResourceFile } from './core/iam/resource-sync';
+
+export type { ResourceDefinition, ResourceFile } from './core/iam/resource-sync';
+/** JSON Schema types and the inferred TypeScript type helpers used by the schema builder. */
+export type { FortressSchema, Infer, JSONSchema, Simplify } from './core/json-schema';
+
+/** Canonical route-security manifest and drift checker. */
+export { detectRouteManifestDrift, hasRouteManifestDrift } from './core/manifest/drift';
+
+export type { DetectRouteManifestDriftOptions, RouteManifestDrift } from './core/manifest/drift';
+
+export { buildRouteManifest } from './core/manifest/route-manifest';
+export type { RouteClassification, RouteManifestEntry } from './core/manifest/route-manifest';
+/** Fortress schema migration metadata and runner helpers. */
+export { detectMigrationDrift, getMigrationStatus, hasMigrationDrift, migrateDown, migrateUp } from './core/migrations/engine';
+export type { MigrationApplyResult, MigrationDownResult, MigrationDrift, MigrationStatus } from './core/migrations/engine';
+
+export { FORTRESS_TABLES, fortressMigrations, getExpectedColumns, getFortressMigrations, getLatestMigrationVersion, getMigrationUpSql } from './core/migrations/migrations';
+export type { FortressMigration, MigrationDialect } from './core/migrations/migrations';
+export type { Unsubscribe } from './core/observability/listener-list';
+/** Runtime-neutral logging, telemetry, and observer contracts. */
+export type { FortressLogger } from './core/observability/logger';
+
+export type {
+  Attributes,
+  AttributeValue,
+  Counter,
+  Histogram,
+  Meter,
+  Span,
+  TelemetryProvider,
+  Tracer,
+} from './core/observability/types';
+
+export { toOpenAPI } from './core/openapi';
+
+export type { ToOpenAPIOptions } from './core/openapi';
+/**
+ * Plugin authoring types — implement {@link FortressPlugin} to extend fortress
+ * with new models, hooks, methods, routes, middleware, scope rules, or
+ * adapter wrappers.
+ */
+export type {
+  AfterHookContext,
+  FieldDefinition,
+  FortressPlugin,
+  HookContext,
+  HookResult,
+  MiddlewareDefinition,
+  ModelConstraint,
+  ModelDefinition,
+  PluginContext,
+  PluginHooks,
+  PostAuthGateContext,
+  PostAuthGateDecision,
+  PostAuthGateProvider,
+  PostAuthGateVerificationContext,
+} from './core/plugin';
+/** Type-level mapping helpers used to expose plugin methods and typed call maps on the fortress instance. */
+export type { CallableForEndpoints, InferPluginCallMap, InferPlugins, PluginMethodsMap } from './core/plugin-methods-map';
+/** Declarative policy-as-code: loader, diff, and apply primitives. */
+export { applyPolicyPlan, applyResourceOps } from './core/policy/apply';
+export type { ApplyPolicyResult } from './core/policy/apply';
+export { diffPolicy } from './core/policy/diff';
+export { DEFAULT_POLICY_FILE, loadPolicy, parsePolicyDocument, resolvePolicyPath } from './core/policy/loader';
+export type { LoadPolicyOptions } from './core/policy/loader';
+
+export type { DiffPolicyOptions, PolicyDocument, PolicyGroup, PolicyOp, PolicyPermission, PolicyPlan, PolicyResource, PolicyRole, PolicyServiceAccount } from './core/policy/types';
+
+/**
+ * Fluent JSON Schema builder DSL. Compose `obj`, `str`, `int`, `arr`, etc.
+ * to build typed endpoint inputs/outputs that double as runtime validators
+ * and OpenAPI component schemas.
+ */
+export {
+  anyOf,
+  arr,
+  bool,
+  date,
+  datetime,
+  defineComponents,
+  discriminatedUnion,
+  email,
+  endpoint,
+  EndpointBuilder,
+  enums,
+  ErrorEnvelope,
+  extractJsonSchema,
+  id,
+  int,
+  intersect,
+  isFortressSchema,
+  isStandardSchema,
+  literal,
+  nullable,
+  nullType,
+  num,
+  obj,
+  oneOf,
+  record,
+  recordOf,
+  ref,
+  str,
+  strFormat,
+  strict,
+  time,
+  url,
+  uuid,
+} from './core/schema-builder';
+
+/** Input type accepted by `endpoint(...).input()` and friends. */
+export type { NumberOptions, SchemaInput, StringOptions } from './core/schema-builder';
+/** Standard Schema v1 interop type — fortress schemas implement this. */
+export type { StandardSchemaV1 } from './core/standard-schema';
+
+/**
+ * Core domain types — users, identifiers, groups, roles, permissions, and
+ * the auth result shapes returned by sign-in / refresh / impersonate.
+ */
+export type {
+  AuthChallenge,
+  AuthImpersonation,
+  AuthMethod,
+  AuthPending,
+  AuthResult,
+  AuthSuccess,
+  AuthTokenPair,
+  ConditionRef,
+  ConditionValue,
+  CreateUserInput,
+  FortressUser,
+  Group,
+  LoginIdentifier,
+  LoginIdentifierType,
+  PendingReason,
+  Permission,
+  PermissionCondition,
+  PermissionContext,
+  PermissionInput,
+  RequestMeta,
+  Role,
+  RoleBinding,
+  SubjectType,
+  TokenClaims,
+} from './core/types';
+
+/** Runtime guards for narrowing an {@link AuthResult} (`status`-discriminated). */
+export { assertSuccess, isImpersonation, isPending, isSuccess } from './core/types';
+
+/**
+ * Framework-agnostic validation primitive. Validates a `{ body, query, params }`
+ * object against an `EndpointInput`, aggregates all issues, and throws
+ * `Errors.validationError` (HTTP 422, code `VALIDATION_ERROR`) on failure.
+ * Use this from any runtime — SvelteKit `+server.ts`, Next.js route handlers,
+ * Bun.serve, Deno, or custom middleware — to validate consumer-defined routes
+ * with the same shape fortress's own dispatch uses internally.
+ */
+export { validateRequest } from './core/validation';
+
+/** Type-safe method surface contributed by the API key plugin. */
+export type { ApiKeyMethods } from './plugins/api-key';
+
+/** Type-safe method surface contributed by the audit log plugin. */
+export type { AuditLogMethods } from './plugins/audit-log';
+
+/** Type-safe method surface contributed by the data isolation plugin. */
+export type { DataIsolationMethods } from './plugins/data-isolation';
+
+/** Type-safe method surface contributed by the email verification plugin. */
+export type { EmailVerificationMethods } from './plugins/email-verification';
+
+/** Type-safe method surface contributed by the magic-link plugin. */
+export type { MagicLinkMethods } from './plugins/magic-link';
+
+/** Type-safe method surface and request/response shapes for the OAuth server plugin. */
+export type { AuthorizeRequestParams, ClientAuth, OAuthMethods, PendingFlowRecord, TokenRequestBody } from './plugins/oauth';
+
+export type { OpenAPISpec, SpecBuilderOptions } from './plugins/openapi/spec-builder';
+
+/** Type-safe method surface contributed by the social login plugin. */
+export type { SocialLoginMethods } from './plugins/social-login';
+
+/** Type-safe method surface contributed by the tenancy plugin. */
+export type { TenancyMethods } from './plugins/tenancy';
+
+/** Type-safe method surface contributed by the two-factor plugin. */
+export type { TwoFactorMethods } from './plugins/two-factor';
+
+/** Type-safe method surface contributed by the WebAuthn plugin. */
+export type { WebAuthnMethods } from './plugins/webauthn';