@facilis.dev/core 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 facilis-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @facilis.dev/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Facilis framework core: configuration contract, authorized-handler types and manifest shapes.
+
+Part of [Facilis](https://github.com/facilis-dev/facilis), a browser-first low-code framework: the Studio
+runs a generated project in a WebContainer where vite dev is the only dev server
+and Nitro v3 runs as a Vite plugin. Framework contracts live in
+[docs/SPEC.md](https://github.com/facilis-dev/facilis/blob/main/docs/SPEC.md) and architectural decisions in
+[docs/DECISIONS.md](https://github.com/facilis-dev/facilis/blob/main/docs/DECISIONS.md).
+
+```sh
+npm install @facilis.dev/core
+```
+
+The package publishes its TypeScript sources and its compiled dist/; the exports map
+of the published manifest points at dist/, so Node and bundlers load JavaScript and
+the bundled .d.ts files.
+
+Licensed under the MIT License.

package/dist/api-clients-config.d.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+/**
+ * Programmatic API clients (V3a): `auth.apiClients`. Opt-in, because a project that never
+ * needs machine credentials should not expose an API-client surface at all.
+ */
+/** Rate limit of the framework token endpoint, per client id (D-143). */
+export interface FacilisApiClientsRateLimitConfig {
+    /** Window the exchange count is measured over. */
+    readonly windowMs: number;
+    /** Token exchanges allowed per client id in one window. */
+    readonly maxRequests: number;
+}
+export interface FacilisApiClientsConfig {
+    readonly enabled: boolean;
+    /** Lifetime of an issued access token: a positive whole number of milliseconds. */
+    readonly tokenTtlMs: number;
+    /** Per-client limit of the token endpoint (D-143); in-process and per-window. */
+    readonly rateLimit: FacilisApiClientsRateLimitConfig;
+}
+/** Authored form of `auth.apiClients`: every key has the framework default. */
+export interface FacilisApiClientsConfigInput {
+    readonly enabled?: boolean;
+    readonly tokenTtlMs?: number;
+    readonly rateLimit?: {
+        readonly windowMs?: number;
+        readonly maxRequests?: number;
+    };
+}
+export declare const apiClientsSchema: z.ZodDefault<z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    tokenTtlMs: z.ZodDefault<z.ZodNumber>;
+    rateLimit: z.ZodDefault<z.ZodObject<{
+        windowMs: z.ZodDefault<z.ZodNumber>;
+        maxRequests: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>>;

package/dist/api-clients-config.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+const DEFAULT_API_TOKEN_TTL_MS = 1000 * 60 * 60;
+// A client may exchange its secret 30 times a minute: token lifetimes are an hour, so a
+// legitimate caller renews once, while a secret-guessing loop is throttled to a crawl.
+const DEFAULT_API_CLIENT_RATE_LIMIT = { windowMs: 60_000, maxRequests: 30 };
+// API clients are opt-in (disabled by default) and their token lifetime is a whole positive
+// number of milliseconds: one hour, short enough that a leaked token ages out quickly.
+const DEFAULT_API_CLIENTS_CONFIG = {
+    enabled: false,
+    tokenTtlMs: DEFAULT_API_TOKEN_TTL_MS,
+    rateLimit: DEFAULT_API_CLIENT_RATE_LIMIT,
+};
+export const apiClientsSchema = z
+    .strictObject({
+    enabled: z.boolean().default(false),
+    tokenTtlMs: z.number().int().positive().default(DEFAULT_API_TOKEN_TTL_MS),
+    rateLimit: z
+        .strictObject({
+        windowMs: z.number().int().positive().default(DEFAULT_API_CLIENT_RATE_LIMIT.windowMs),
+        maxRequests: z.number().int().positive().default(DEFAULT_API_CLIENT_RATE_LIMIT.maxRequests),
+    })
+        .default(() => DEFAULT_API_CLIENT_RATE_LIMIT),
+})
+    .default(() => DEFAULT_API_CLIENTS_CONFIG);

package/dist/config-validation.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+import type { FacilisConfig } from "./config.js";
+/** Refinement run by `facilisConfigSchema`: every cross-section rule in one place. */
+export declare function crossCheckConfig(config: FacilisConfig, ctx: z.RefinementCtx): void;

package/dist/config-validation.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { checkSsoConfig } from "./sso-config.js";
+/**
+ * Cross-section validation for `facilis.config.ts` (SPEC §7.1, §8.4.1).
+ *
+ * The per-section Zod schemas only see their own object; these checks need the whole config
+ * (a role names a declared permission, SSO names an existing role, S3 names its bucket). They
+ * live here so `config.ts` stays under the 300-line limit and so the auth/storage/SSO rules
+ * have one reviewable home.
+ */
+/**
+ * Permissions are stable identifiers: a role may only reference permissions declared in
+ * `auth.permissions`, and the wildcard is a role-only shorthand (SPEC §8.4.1).
+ */
+const WILDCARD_PERMISSION = "*";
+function addIssue(ctx, path, message) {
+    ctx.addIssue({ code: "custom", message, path: [...path] });
+}
+function reportDuplicates(values, path, ctx, label) {
+    const seen = new Set();
+    for (const [index, value] of values.entries()) {
+        if (seen.has(value))
+            addIssue(ctx, [...path, index], `duplicate ${label} "${value}"`);
+        seen.add(value);
+    }
+}
+function ownRole(config, role) {
+    // A record from JSON can inherit Object.prototype keys, so membership must be own-only.
+    return Object.hasOwn(config.auth.roles, role) ? config.auth.roles[role] : undefined;
+}
+/** Refinement run by `facilisConfigSchema`: every cross-section rule in one place. */
+export function crossCheckConfig(config, ctx) {
+    const declared = new Set(config.auth.permissions);
+    if (declared.has(WILDCARD_PERMISSION)) {
+        addIssue(ctx, ["auth", "permissions"], `"${WILDCARD_PERMISSION}" is only valid inside auth.roles; declare permissions explicitly`);
+    }
+    reportDuplicates(config.auth.permissions, ["auth", "permissions"], ctx, "permission");
+    for (const [role, permissions] of Object.entries(config.auth.roles)) {
+        const seen = new Set();
+        for (const [index, permission] of permissions.entries()) {
+            if (permission === WILDCARD_PERMISSION)
+                continue;
+            if (!declared.has(permission)) {
+                addIssue(ctx, ["auth", "roles", role, index], `role "${role}" references unknown permission "${permission}"; declare it in auth.permissions`);
+            }
+            if (seen.has(permission)) {
+                addIssue(ctx, ["auth", "roles", role, index], `role "${role}" repeats "${permission}"`);
+            }
+            seen.add(permission);
+        }
+    }
+    if (ownRole(config, config.auth.defaultRole) === undefined) {
+        addIssue(ctx, ["auth", "defaultRole"], `defaultRole "${config.auth.defaultRole}" is not a key of auth.roles`);
+    }
+    if (config.storage.driver === "s3") {
+        if (config.storage.bucket === null) {
+            addIssue(ctx, ["storage", "bucket"], 'storage.bucket is required when storage.driver is "s3"');
+        }
+        if (config.storage.region === null) {
+            addIssue(ctx, ["storage", "region"], 'storage.region is required when storage.driver is "s3"');
+        }
+    }
+    if (!config.i18n.locales.includes(config.i18n.defaultLocale)) {
+        addIssue(ctx, ["i18n", "defaultLocale"], `defaultLocale "${config.i18n.defaultLocale}" must be listed in i18n.locales`);
+    }
+    // SSO provider ids are URL segments and their roles must exist in auth.roles (D-120).
+    checkSsoConfig(config.auth.sso, config.auth, ctx);
+}

package/dist/config.d.ts

@@ -0,0 +1,264 @@
+import { z } from "zod";
+import { type FacilisApiClientsConfig, type FacilisApiClientsConfigInput } from "./api-clients-config.js";
+import { type FacilisJobsConfig, type FacilisJobsConfigInput } from "./jobs-config.js";
+import { type FacilisWorkflowsConfig, type FacilisWorkflowsConfigInput } from "./workflows-config.js";
+import { type FacilisLoggingConfig, type FacilisLoggingConfigInput } from "./logging-config.js";
+import { type FacilisSsoConfig, type FacilisSsoConfigInput } from "./sso-config.js";
+import { type FacilisEmailVerificationConfig, type FacilisEmailVerificationConfigInput } from "./verification-config.js";
+import { type FacilisSecurityConfig } from "./security-config.js";
+import { type FacilisStorageConfig, type FacilisStorageConfigInput } from "./storage-config.js";
+export { DEFAULT_LOGGING_CONFIG, facilisLoggingConfigSchema } from "./logging-config.js";
+export type { FacilisLoggingConfig, FacilisLoggingConfigInput } from "./logging-config.js";
+export { DEFAULT_SSO_CONFIG, SSO_PROVIDER_KINDS, ssoConfigSchema, ssoProviderSchema, } from "./sso-config.js";
+export type { FacilisSsoConfig, FacilisSsoConfigInput, FacilisSsoProvider, SsoProviderKind, } from "./sso-config.js";
+export { DEFAULT_EMAIL_VERIFICATION_CONFIG, facilisEmailVerificationConfigSchema, } from "./verification-config.js";
+export type { FacilisEmailVerificationConfig, FacilisEmailVerificationConfigInput, } from "./verification-config.js";
+export type { FacilisSecurityConfig } from "./security-config.js";
+export { DEFAULT_JOBS_CONFIG, facilisJobsConfigSchema } from "./jobs-config.js";
+export type { FacilisJobsConfig, FacilisJobsConfigInput } from "./jobs-config.js";
+export { DEFAULT_WORKFLOWS_CONFIG, facilisWorkflowsConfigSchema } from "./workflows-config.js";
+export type { FacilisWorkflowsConfig, FacilisWorkflowsConfigInput } from "./workflows-config.js";
+export { DEFAULT_STORAGE_CONFIG, STORAGE_DRIVERS } from "./storage-config.js";
+export type { FacilisStorageConfig, FacilisStorageConfigInput, FacilisStorageEncryptionConfig, StorageDriverKind, } from "./storage-config.js";
+/**
+ * The configuration contract of a Facilis project (SPEC §7.1).
+ *
+ * Everything here is declared in the project's `facilis.config.ts` and is therefore code:
+ * reviewable, diffable and the only source of truth for roles and permissions (SPEC §8.4.1).
+ */
+/** Database driver modes supported by `@facilis.dev/db` (SPEC §7.1). */
+export declare const DB_MODES: readonly ["pglite", "postgres", "json"];
+export type DbMode = (typeof DB_MODES)[number];
+export interface FacilisReleaseConfig {
+    readonly ref: string;
+}
+export interface FacilisDbConfig {
+    readonly mode: DbMode;
+    readonly migrationsDir: string;
+    readonly tenantColumns: readonly string[];
+    readonly ownerColumns: readonly string[];
+}
+export interface FacilisI18nConfig {
+    readonly defaultLocale: string;
+    readonly locales: readonly string[];
+}
+export interface FacilisAuthConfig {
+    readonly permissions: readonly string[];
+    /** Role name → permission names. `"*"` is only valid here, as "every declared permission". */
+    readonly roles: Readonly<Record<string, readonly string[]>>;
+    readonly defaultRole: string;
+    readonly sessionDurationMs: number;
+    /** External identity providers (D-120); `providers: []` when the app uses passwords only. */
+    readonly sso: FacilisSsoConfig;
+    /** Email verification for password accounts (D-156); disabled by default. */
+    readonly verification: FacilisEmailVerificationConfig;
+    /** Bearer-token API clients (V3a): opt-in, with a token lifetime. */
+    readonly apiClients: FacilisApiClientsConfig;
+}
+/**
+ * Nitro options owned by the project (D-034).
+ *
+ * Facilis validates only the shape — an object — and passes every key to Nitro untouched:
+ * these are Nitro's options, not the framework's. `@facilis.dev/nitro` merges them over the
+ * Facilis defaults (`serverDir: "./server"`, `experimental.openAPI: true`), so a project
+ * only declares what it changes.
+ */
+export type FacilisNitroOptions = Readonly<Record<string, unknown>>;
+export interface FacilisConfig {
+    readonly release: FacilisReleaseConfig;
+    readonly db: FacilisDbConfig;
+    readonly i18n: FacilisI18nConfig;
+    readonly auth: FacilisAuthConfig;
+    /** Background-job queue settings (D-107, docs/JOBS.md §4). */
+    readonly jobs: FacilisJobsConfig;
+    /** Workflow runner settings (D-135, docs/WORKFLOWS.md §10). */
+    readonly workflows: FacilisWorkflowsConfig;
+    /** Binary uploads (D-053): driver, bucket and the framework limits. */
+    readonly storage: FacilisStorageConfig;
+    /** Request-origin policy; always present so the wrapper never guesses (SPEC §8). */
+    readonly security: FacilisSecurityConfig;
+    /** Operator logging defaults (D-119): level and what is collected; sinks are env-owned. */
+    readonly logging: FacilisLoggingConfig;
+    readonly nitro: FacilisNitroOptions;
+}
+/**
+ * Authored form of the config: everything has a default except the auth declaration, and
+ * arrays are readonly so a fully-typed `FacilisConfig` can be passed back in unchanged.
+ */
+export interface FacilisConfigInput {
+    readonly release?: {
+        readonly ref?: string;
+    };
+    readonly db?: {
+        readonly mode?: DbMode;
+        readonly migrationsDir?: string;
+        readonly tenantColumns?: readonly string[];
+        readonly ownerColumns?: readonly string[];
+    };
+    readonly i18n?: {
+        readonly defaultLocale?: string;
+        readonly locales?: readonly string[];
+    };
+    /** Passed to Nitro unchanged; `@facilis.dev/nitro` merges the framework defaults underneath. */
+    readonly nitro?: FacilisNitroOptions;
+    readonly auth: {
+        readonly permissions?: readonly string[];
+        readonly roles?: Readonly<Record<string, readonly string[]>>;
+        readonly defaultRole: string;
+        readonly sessionDurationMs?: number;
+        /** External identity providers (D-120); every key has a default. */
+        readonly sso?: FacilisSsoConfigInput;
+        /** Email verification for password accounts (D-156); every key has a default. */
+        readonly verification?: FacilisEmailVerificationConfigInput;
+        /** Bearer-token API clients (V3a); optional, disabled by default. */
+        readonly apiClients?: FacilisApiClientsConfigInput;
+    };
+    /** Background-job queue settings; every key has a default (D-107). */
+    readonly jobs?: FacilisJobsConfigInput;
+    /** Workflow runner settings (D-135); every key has a default. */
+    readonly workflows?: FacilisWorkflowsConfigInput;
+    /** Binary uploads (D-053, D-117); every key has a default. */
+    readonly storage?: FacilisStorageConfigInput;
+    /** Logging defaults (D-119); every key has a default and the environment overrides them. */
+    readonly logging?: FacilisLoggingConfigInput;
+    /** Request-origin allow-list; defaults to same-origin only. */
+    readonly security?: {
+        readonly trustedOrigins?: readonly string[];
+    };
+}
+/**
+ * Zod schema for the complete `FacilisConfig` shape.
+ *
+ * Sections other than `auth` have documented defaults so a generated project can grow into
+ * them; the auth block is always explicit and cross-checked (SPEC §8.4.1).
+ */
+export declare const facilisConfigSchema: z.ZodObject<{
+    release: z.ZodDefault<z.ZodObject<{
+        ref: z.ZodString;
+    }, z.core.$strict>>;
+    db: z.ZodDefault<z.ZodObject<{
+        mode: z.ZodDefault<z.ZodEnum<{
+            json: "json";
+            pglite: "pglite";
+            postgres: "postgres";
+        }>>;
+        migrationsDir: z.ZodDefault<z.ZodString>;
+        tenantColumns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        ownerColumns: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    i18n: z.ZodDefault<z.ZodObject<{
+        defaultLocale: z.ZodDefault<z.ZodString>;
+        locales: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    auth: z.ZodObject<{
+        permissions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        roles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+        defaultRole: z.ZodString;
+        sessionDurationMs: z.ZodDefault<z.ZodNumber>;
+        sso: z.ZodDefault<z.ZodObject<{
+            providers: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodOptional<z.ZodString>;
+                autoProvision: z.ZodDefault<z.ZodBoolean>;
+                defaultRole: z.ZodOptional<z.ZodString>;
+                kind: z.ZodLiteral<"oidc">;
+                issuer: z.ZodString;
+                clientId: z.ZodString;
+                clientSecretEnv: z.ZodOptional<z.ZodString>;
+                scopes: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+                tokenAuth: z.ZodDefault<z.ZodEnum<{
+                    client_secret_basic: "client_secret_basic";
+                    client_secret_post: "client_secret_post";
+                    none: "none";
+                }>>;
+                assumeEmailVerified: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strict>, z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodOptional<z.ZodString>;
+                autoProvision: z.ZodDefault<z.ZodBoolean>;
+                defaultRole: z.ZodOptional<z.ZodString>;
+                kind: z.ZodLiteral<"oauth2">;
+                authorizationEndpoint: z.ZodString;
+                tokenEndpoint: z.ZodString;
+                userinfoEndpoint: z.ZodString;
+                clientId: z.ZodString;
+                clientSecretEnv: z.ZodOptional<z.ZodString>;
+                scopes: z.ZodDefault<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+                tokenAuth: z.ZodDefault<z.ZodEnum<{
+                    client_secret_basic: "client_secret_basic";
+                    client_secret_post: "client_secret_post";
+                    none: "none";
+                }>>;
+                mapping: z.ZodObject<{
+                    subject: z.ZodString;
+                    email: z.ZodString;
+                    emailVerified: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>;
+                assumeEmailVerified: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strict>, z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodOptional<z.ZodString>;
+                autoProvision: z.ZodDefault<z.ZodBoolean>;
+                defaultRole: z.ZodOptional<z.ZodString>;
+                kind: z.ZodLiteral<"saml">;
+                entryPoint: z.ZodString;
+                issuer: z.ZodString;
+                certificateEnv: z.ZodString;
+                emailAttribute: z.ZodDefault<z.ZodString>;
+                wantAssertionsSigned: z.ZodDefault<z.ZodBoolean>;
+                wantResponseSigned: z.ZodDefault<z.ZodBoolean>;
+            }, z.core.$strict>], "kind">>>>;
+            failureRedirect: z.ZodDefault<z.ZodString>;
+            stateTtlMs: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+        verification: z.ZodType<FacilisEmailVerificationConfig, unknown, z.core.$ZodTypeInternals<FacilisEmailVerificationConfig, unknown>>;
+        apiClients: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            tokenTtlMs: z.ZodDefault<z.ZodNumber>;
+            rateLimit: z.ZodDefault<z.ZodObject<{
+                windowMs: z.ZodDefault<z.ZodNumber>;
+                maxRequests: z.ZodDefault<z.ZodNumber>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    jobs: z.ZodDefault<z.ZodObject<{
+        maxConcurrent: z.ZodDefault<z.ZodNumber>;
+        maxAttempts: z.ZodDefault<z.ZodNumber>;
+        retryDelayMs: z.ZodDefault<z.ZodNumber>;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        pollIntervalMs: z.ZodDefault<z.ZodNumber>;
+        persist: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    workflows: z.ZodDefault<z.ZodObject<{
+        tickIntervalMs: z.ZodDefault<z.ZodNumber>;
+        persist: z.ZodDefault<z.ZodBoolean>;
+        defaultTaskTtlMs: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strict>>;
+    storage: z.ZodDefault<z.ZodObject<{
+        driver: z.ZodDefault<z.ZodEnum<{
+            local: "local";
+            s3: "s3";
+        }>>;
+        bucket: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        region: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        endpoint: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        forcePathStyle: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
+        maxUploadBytes: z.ZodDefault<z.ZodNumber>;
+        tokenTtlSeconds: z.ZodDefault<z.ZodNumber>;
+        encryption: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    security: z.ZodDefault<z.ZodObject<{
+        trustedOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    logging: z.ZodType<FacilisLoggingConfig, unknown, z.core.$ZodTypeInternals<FacilisLoggingConfig, unknown>>;
+    nitro: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+/**
+ * Validates `facilis.config.ts` and returns the resolved, full config.
+ *
+ * Throws a readable error instead of returning a partially valid contract: a project with
+ * unknown role permissions must fail at boot (SPEC §8.4.1), not on the first request.
+ */
+export declare function defineConfig(config: FacilisConfigInput): FacilisConfig;

package/dist/config.js

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import { apiClientsSchema, } from "./api-clients-config.js";
+import { facilisJobsConfigSchema, } from "./jobs-config.js";
+import { facilisWorkflowsConfigSchema, } from "./workflows-config.js";
+import { facilisLoggingConfigSchema, } from "./logging-config.js";
+import { ssoConfigSchema, } from "./sso-config.js";
+import { facilisEmailVerificationConfigSchema, } from "./verification-config.js";
+import { securityConfigSchema, } from "./security-config.js";
+import { crossCheckConfig } from "./config-validation.js";
+import { facilisStorageConfigSchema, } from "./storage-config.js";
+export { DEFAULT_LOGGING_CONFIG, facilisLoggingConfigSchema } from "./logging-config.js";
+export { DEFAULT_SSO_CONFIG, SSO_PROVIDER_KINDS, ssoConfigSchema, ssoProviderSchema, } from "./sso-config.js";
+export { DEFAULT_EMAIL_VERIFICATION_CONFIG, facilisEmailVerificationConfigSchema, } from "./verification-config.js";
+export { DEFAULT_JOBS_CONFIG, facilisJobsConfigSchema } from "./jobs-config.js";
+export { DEFAULT_WORKFLOWS_CONFIG, facilisWorkflowsConfigSchema } from "./workflows-config.js";
+export { DEFAULT_STORAGE_CONFIG, STORAGE_DRIVERS } from "./storage-config.js";
+/**
+ * The configuration contract of a Facilis project (SPEC §7.1).
+ *
+ * Everything here is declared in the project's `facilis.config.ts` and is therefore code:
+ * reviewable, diffable and the only source of truth for roles and permissions (SPEC §8.4.1).
+ */
+/** Database driver modes supported by `@facilis.dev/db` (SPEC §7.1). */
+export const DB_MODES = ["pglite", "postgres", "json"];
+const DEFAULT_RELEASE_REF = "main";
+const DEFAULT_MIGRATIONS_DIR = "./drizzle";
+const DEFAULT_TENANT_COLUMN = "tenantId";
+const DEFAULT_OWNER_COLUMN = "ownerId";
+const DEFAULT_LOCALE = "en";
+const DEFAULT_SESSION_DURATION_MS = 1000 * 60 * 60 * 24 * 7;
+const DEFAULT_DB_CONFIG = {
+    mode: "pglite",
+    migrationsDir: DEFAULT_MIGRATIONS_DIR,
+    tenantColumns: [DEFAULT_TENANT_COLUMN],
+    ownerColumns: [DEFAULT_OWNER_COLUMN],
+};
+const DEFAULT_I18N_CONFIG = { defaultLocale: DEFAULT_LOCALE, locales: [DEFAULT_LOCALE] };
+const releaseSchema = z
+    .strictObject({
+    ref: z.string().min(1, "release.ref must be a non-empty git ref"),
+})
+    // A generated project boots against its own branch; `main` is the least surprising default.
+    .default({ ref: DEFAULT_RELEASE_REF });
+const dbSchema = z
+    .strictObject({
+    mode: z.enum(DB_MODES).default("pglite"),
+    migrationsDir: z.string().min(1).default(DEFAULT_MIGRATIONS_DIR),
+    tenantColumns: z.array(z.string().min(1)).default([DEFAULT_TENANT_COLUMN]),
+    ownerColumns: z.array(z.string().min(1)).default([DEFAULT_OWNER_COLUMN]),
+})
+    .default(() => DEFAULT_DB_CONFIG);
+const i18nSchema = z
+    .strictObject({
+    defaultLocale: z.string().min(1).default(DEFAULT_LOCALE),
+    locales: z.array(z.string().min(1)).default([DEFAULT_LOCALE]),
+})
+    .default(() => DEFAULT_I18N_CONFIG);
+// Nitro's own options are not Facilis's contract, so the section is a pass-through: keep
+// the object as authored and let @facilis.dev/nitro apply the framework defaults underneath.
+const nitroSchema = z.record(z.string(), z.unknown()).default({});
+// Session duration is a safe default (one week, matching SPEC §8.4.1's example); everything
+// security-relevant (roles, permissions, default role) stays required so it is never implicit.
+const authSchema = z.strictObject({
+    permissions: z.array(z.string().min(1)).default([]),
+    roles: z.record(z.string().min(1), z.array(z.string().min(1))).default({}),
+    defaultRole: z.string().min(1),
+    sessionDurationMs: z.number().int().positive().default(DEFAULT_SESSION_DURATION_MS),
+    sso: ssoConfigSchema,
+    verification: facilisEmailVerificationConfigSchema,
+    apiClients: apiClientsSchema,
+});
+const baseConfigSchema = z.strictObject({
+    release: releaseSchema,
+    db: dbSchema,
+    i18n: i18nSchema,
+    auth: authSchema,
+    jobs: facilisJobsConfigSchema,
+    workflows: facilisWorkflowsConfigSchema,
+    storage: facilisStorageConfigSchema,
+    security: securityConfigSchema,
+    logging: facilisLoggingConfigSchema,
+    nitro: nitroSchema,
+});
+/**
+ * Zod schema for the complete `FacilisConfig` shape.
+ *
+ * Sections other than `auth` have documented defaults so a generated project can grow into
+ * them; the auth block is always explicit and cross-checked (SPEC §8.4.1).
+ */
+export const facilisConfigSchema = baseConfigSchema.superRefine(crossCheckConfig);
+/**
+ * Validates `facilis.config.ts` and returns the resolved, full config.
+ *
+ * Throws a readable error instead of returning a partially valid contract: a project with
+ * unknown role permissions must fail at boot (SPEC §8.4.1), not on the first request.
+ */
+export function defineConfig(config) {
+    const result = facilisConfigSchema.safeParse(config);
+    if (!result.success) {
+        throw new Error(`Invalid facilis config:\n${z.prettifyError(result.error)}`);
+    }
+    return result.data;
+}

package/dist/errors.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+/**
+ * Canonical API error contract (contracts §4.4, decision O-002).
+ *
+ * Responses carry codes, never prose: user-facing strings are translated client-side from
+ * `t("error.<code>")` so the API stays locale-neutral.
+ */
+export declare const FACILIS_ERROR_CODES: readonly ["unauthorized", "forbidden", "email_unverified", "invalid_input", "too_many_requests", "unsupported_media_type", "conflict", "db_unavailable", "not_found", "storage_unavailable", "payload_too_large", "file_too_large", "table_not_declared", "raw_sql_not_allowed", "internal_error"];
+export type FacilisErrorCode = (typeof FACILIS_ERROR_CODES)[number];
+/** HTTP status per code — the only place a status is chosen (contracts §4.4). */
+export declare const FACILIS_ERROR_STATUS: Readonly<Record<FacilisErrorCode, number>>;
+export interface FacilisErrorBody {
+    code: FacilisErrorCode;
+    details?: unknown;
+}
+/**
+ * Builds the web `Response` for a Facilis error. Handlers return these directly; `h3`
+ * treats a returned Response as the final response (contracts §4.4).
+ */
+export declare function fail(code: FacilisErrorCode, details?: unknown): Response;
+/** Flattens Zod issues into the `details` shape used by `invalid_input` responses. */
+export declare function flattenZodIssues(error: z.ZodError): {
+    formErrors: string[];
+    fieldErrors: {};
+};
+/** `400 invalid_input` with the flattened Zod issues as `details` (contracts §4.4). */
+export declare function invalidInput(error: z.ZodError): Response;

package/dist/errors.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+/**
+ * Canonical API error contract (contracts §4.4, decision O-002).
+ *
+ * Responses carry codes, never prose: user-facing strings are translated client-side from
+ * `t("error.<code>")` so the API stays locale-neutral.
+ */
+export const FACILIS_ERROR_CODES = [
+    "unauthorized",
+    "forbidden",
+    // 403: the password was correct but the account has not verified its email yet (D-156).
+    "email_unverified",
+    "invalid_input",
+    // 429: a caller exceeded a framework rate limit (D-143); the response carries `retry-after`.
+    "too_many_requests",
+    // 415: a body-carrying route was called with the wrong media type; the body is not read.
+    "unsupported_media_type",
+    "conflict",
+    "db_unavailable",
+    "not_found",
+    "storage_unavailable",
+    // 413: the request body exceeds the wrapper cap before parsing (SEC-09).
+    "payload_too_large",
+    "file_too_large",
+    // 500: the runtime guard refused a relation outside the route's dbTables (D-157).
+    "table_not_declared",
+    // 500: db.execute was used without rawSql: true on the route (D-157).
+    "raw_sql_not_allowed",
+    "internal_error",
+];
+/** HTTP status per code — the only place a status is chosen (contracts §4.4). */
+export const FACILIS_ERROR_STATUS = {
+    unauthorized: 401,
+    forbidden: 403,
+    email_unverified: 403,
+    invalid_input: 400,
+    too_many_requests: 429,
+    unsupported_media_type: 415,
+    conflict: 409,
+    db_unavailable: 500,
+    not_found: 404,
+    storage_unavailable: 503,
+    // 413: the request body exceeds the wrapper cap before parsing (SEC-09).
+    payload_too_large: 413,
+    // 413: the upload is a valid form, but the file exceeds storage.maxUploadBytes.
+    file_too_large: 413,
+    // 500: a route reached an undeclared relation or raw SQL without the flag (D-157).
+    table_not_declared: 500,
+    raw_sql_not_allowed: 500,
+    internal_error: 500,
+};
+/**
+ * Builds the web `Response` for a Facilis error. Handlers return these directly; `h3`
+ * treats a returned Response as the final response (contracts §4.4).
+ */
+export function fail(code, details) {
+    const body = details === undefined ? { code } : { code, details };
+    const headers = new Headers({ "content-type": "application/json; charset=utf-8" });
+    return new Response(JSON.stringify(body), { status: FACILIS_ERROR_STATUS[code], headers });
+}
+/** Flattens Zod issues into the `details` shape used by `invalid_input` responses. */
+export function flattenZodIssues(error) {
+    return z.flattenError(error);
+}
+/** `400 invalid_input` with the flattened Zod issues as `details` (contracts §4.4). */
+export function invalidInput(error) {
+    return fail("invalid_input", flattenZodIssues(error));
+}