@spfn/core 0.3.0-beta.3 → 0.3.0-beta.5

package/dist/server/index.d.ts

@@ -10,8 +10,13 @@ import { b as EventRouterDef, E as EventDef } from '../token-manager-BT5EnUAR.js
 import { d as SSEHandlerConfig, e as SSEAuthConfig } from '../types-ZQODsBft.js';
 import { W as WSRouterDef, f as WSHandlerConfig, e as WSMessageHandlers, g as WSAuthConfig } from '../types-2AbaW4Ie.js';
 import { DatabaseProvider, MigrationStatus, MigrationStatusDb } from '@spfn/core/db';
-import '@sinclair/typebox';
+import * as _sinclair_typebox from '@sinclair/typebox';
+import { Static } from '@sinclair/typebox';
+import { R as RouteDef } from '../route-builder-2ani2jEI.js';
 import 'pg-boss';
+import '../define-middleware-CVKgqo8S.js';
+import 'hono/utils/http-status';
+import '../route/types.js';
 
 /**
  * @deprecated Use `loadEnv` from '@spfn/core/env/loader' instead.
@@ -22,6 +27,33 @@ import 'pg-boss';
  */
 declare function loadEnvFiles(): void;
 
+/** Stable operation identity used by separately deployed clients. */
+declare const CORE_TIME_OPERATION_ID = "core.time";
+/**
+ * Closed response shape for the server-time wire capability.
+ *
+ * Millisecond timestamps use integers throughout SPFN's external contracts.
+ */
+declare const ServerTimeResponseSchema: _sinclair_typebox.TObject<{
+    serverTimeMillis: _sinclair_typebox.TInteger;
+}>;
+type ServerTimeResponse = Static<typeof ServerTimeResponseSchema>;
+/** Injectable source of Unix epoch milliseconds. */
+interface ServerClock {
+    now(): number;
+}
+/**
+ * Build the route from a clock so tests and alternate runtimes can supply the
+ * epoch source without replacing global time.
+ */
+declare function createCoreTimeRoute(clock?: ServerClock): RouteDef<{}, {}, {
+    serverTimeMillis: number;
+}>;
+/** The production route and the public wire-contract source of truth. */
+declare const CORE_TIME_ROUTE: RouteDef<{}, {}, {
+    serverTimeMillis: number;
+}>;
+
 /**
  * Workflow router interface for @spfn/core integration
  *
@@ -489,6 +521,15 @@ interface ServerConfig {
          */
         detailed?: boolean;
     };
+    /**
+     * Server-time capability dependencies.
+     *
+     * The endpoint is always enabled at `GET /_core/time`. Supplying a clock is
+     * primarily a deterministic test seam; production defaults to `Date.now()`.
+     */
+    serverTime?: {
+        clock?: ServerClock;
+    };
     /**
      * Migration boot gate
      *
@@ -757,6 +798,13 @@ declare const CORE_NAMESPACE = "/_core";
  * balancer console — and a version bump migrates none of them.
  */
 declare const CORE_HEALTH_PATH = "/_core/health";
+/**
+ * Where clients obtain the server's current Unix epoch in milliseconds.
+ *
+ * This endpoint is registered before application routes and application auth
+ * middleware so a client can call it before it has a proof or session.
+ */
+declare const CORE_TIME_PATH = "/_core/time";
 
 /**
  * Start SPFN Server
@@ -1197,6 +1245,12 @@ declare class ServerConfigBuilder {
      * Configure health check endpoint
      */
     healthCheck(healthCheck: ServerConfig['healthCheck']): this;
+    /**
+     * Supply the clock used by the built-in `GET /_core/time` capability.
+     * Production servers normally keep the default `Date.now()` clock; this is
+     * exposed so tests can assert an exact wire value without replacing globals.
+     */
+    serverTime(serverTime: ServerConfig['serverTime']): this;
     /**
      * Configure infrastructure initialization
      */
@@ -1273,4 +1327,4 @@ declare class ServerConfigBuilder {
  */
 declare function defineServerConfig(): ServerConfigBuilder;
 
-export { type AppFactory, CORE_HEALTH_PATH, CORE_NAMESPACE, type MigrationSnapshot, PendingMigrationsError, type ServerConfig, type ServerInstance, type ShutdownHookOptions, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };
+export { type AppFactory, CORE_HEALTH_PATH, CORE_NAMESPACE, CORE_TIME_OPERATION_ID, CORE_TIME_PATH, CORE_TIME_ROUTE, type MigrationSnapshot, PendingMigrationsError, type ServerClock, type ServerConfig, type ServerInstance, type ServerTimeResponse, ServerTimeResponseSchema, type ShutdownHookOptions, createCoreTimeRoute, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };

package/dist/server/index.js

@@ -13,6 +13,7 @@ import { randomBytes, createHash } from 'crypto';
 import { Agent, setGlobalDispatcher } from 'undici';
 import { initDatabase, getDatabase, hasMigrationTargets, collectMigrationStatus, countPendingMigrations, pendingMigrationTargets, formatPendingMigrations, pendingMigrationsSummary, RUN_MIGRATIONS_HINT, closeDatabase, migrationTargets } from '@spfn/core/db';
 import { initCache, getCache, closeCache } from '@spfn/core/cache';
+import { FormatRegistry, Type } from '@sinclair/typebox';
 import { serve } from '@hono/node-server';
 import PgBoss from 'pg-boss';
 import { networkInterfaces } from 'os';
@@ -354,9 +355,10 @@ function parseEnvFile(filePath) {
   return parse(readFileSync(filePath, "utf-8"));
 }
 function loadEnv(options = {}) {
+  const nodeEnvAtEntry = process.env.NODE_ENV;
   const {
     cwd = process.cwd(),
-    nodeEnv = process.env.NODE_ENV || "local",
+    nodeEnv = nodeEnvAtEntry || "local",
     server = true,
     debug = false,
     override = false
@@ -386,8 +388,30 @@ function loadEnv(options = {}) {
     envLogger.debug(`Loaded env files: ${loadedFiles.join(", ")}`);
     envLogger.debug(`Loaded ${loadedKeys.length} environment variables`);
   }
+  warnIfEnvGuessCostSomething(cwd, nodeEnvAtEntry, options.nodeEnv, nodeEnv);
   return { loadedFiles, loadedKeys };
 }
+function warnIfEnvGuessCostSomething(cwd, nodeEnvAtEntry, explicitNodeEnv, resolvedNodeEnv) {
+  if (nodeEnvAtEntry || explicitNodeEnv) {
+    return;
+  }
+  const declared = process.env.NODE_ENV;
+  if (!declared) {
+    envLogger.warn(
+      `NODE_ENV is not set anywhere; env files were resolved for "${resolvedNodeEnv}". Set NODE_ENV in the process environment to choose the file set.`
+    );
+    return;
+  }
+  if (declared === resolvedNodeEnv) {
+    return;
+  }
+  if (!existsSync(resolve(cwd, `.env.${declared}`))) {
+    return;
+  }
+  envLogger.warn(
+    `.env.${declared} was NOT loaded: NODE_ENV was not set when the process started, so env files were resolved for "${resolvedNodeEnv}" before a file declared NODE_ENV=${declared}. Set NODE_ENV in the process environment, not in a .env file.`
+  );
+}
 
 // src/server/dotenv-loader.ts
 var warned = false;
@@ -1080,6 +1104,7 @@ async function runMigrationBootGate(config, cwd = process.cwd()) {
 // src/server/namespace.ts
 var CORE_NAMESPACE = "/_core";
 var CORE_HEALTH_PATH = `${CORE_NAMESPACE}/health`;
+var CORE_TIME_PATH = `${CORE_NAMESPACE}/time`;
 var LEGACY_HEALTH_PATH = "/health";
 
 // src/server/shutdown-manager.ts
@@ -1480,6 +1505,378 @@ function buildStartupConfig(config, timeouts) {
   };
 }
 
+// src/route/route-builder.ts
+var RouteBuilder = class _RouteBuilder {
+  _method;
+  _path;
+  _input;
+  _interceptor;
+  _middlewares;
+  _skipMiddlewares;
+  _contract;
+  /**
+   * Create a new RouteBuilder with copied properties and optional overrides
+   */
+  clone(overrides) {
+    const builder = new _RouteBuilder();
+    builder._method = this._method;
+    builder._path = this._path;
+    builder._input = overrides?.input ?? this._input;
+    builder._interceptor = overrides?.interceptor ?? this._interceptor;
+    builder._middlewares = overrides?.middlewares ?? this._middlewares;
+    builder._skipMiddlewares = overrides?.skipMiddlewares ?? this._skipMiddlewares;
+    builder._contract = overrides?.contract ?? this._contract;
+    return builder;
+  }
+  /**
+   * Define input schemas
+   *
+   * @example
+   * ```ts
+   * route.get('/users/:id')
+   *   .input({
+   *     params: Type.Object({ id: Type.String() }),
+   *     query: Type.Object({ page: Type.Number() }),
+   *     headers: Type.Object({ authorization: Type.String() })
+   *   })
+   *   .handler(async (c) => {
+   *     const { params, query, headers } = await c.data();
+   *     // params = { id: string }
+   *     // query = { page: number }
+   *     // headers = { authorization: string }
+   *   })
+   * ```
+   */
+  input(input) {
+    return this.clone({ input });
+  }
+  /**
+   * Define fields injected by interceptors
+   *
+   * These fields are:
+   * - Available in the handler (merged with input)
+   * - Excluded from client types (codegen uses only input)
+   * - Not validated by route input schema (injected by middleware)
+   *
+   * Use this when middleware/interceptors add fields to the request
+   * before it reaches the handler.
+   *
+   * @example
+   * ```ts
+   * // Auth interceptor injects crypto key fields
+   * route.post('/_auth/login')
+   *   .input({
+   *     body: Type.Object({
+   *       email: Type.String(),
+   *       password: Type.String()
+   *     })
+   *   })
+   *   .interceptor({
+   *     body: Type.Object({
+   *       publicKey: Type.String(),
+   *       keyId: Type.String(),
+   *       fingerprint: Type.String()
+   *     })
+   *   })
+   *   .handler(async (c) => {
+   *     const { body } = await c.data();
+   *     // body type: { email, password, publicKey, keyId, fingerprint }
+   *     // Client only sees: { email, password }
+   *     return loginService(body);
+   *   });
+   * ```
+   */
+  interceptor(interceptor) {
+    return this.clone({ interceptor });
+  }
+  /**
+   * Add middlewares to the route
+   *
+   * Accepts both regular middleware handlers and named middlewares (NamedMiddleware).
+   * Named middlewares that are already registered globally will be automatically
+   * deduplicated to prevent double execution.
+   *
+   * @example
+   * ```ts
+   * import { authenticate } from '@spfn/auth/server/middleware';
+   *
+   * // With NamedMiddleware (auto-deduped if registered globally)
+   * route.get('/users')
+   *   .use([authenticate, RateLimitMiddleware()])
+   *
+   * // With regular middleware handlers
+   * route.get('/users')
+   *   .use([AuthMiddleware(), RateLimitMiddleware()])
+   * ```
+   */
+  middleware(middlewares) {
+    return this.clone({ middlewares });
+  }
+  /**
+   * Add middlewares to the route (alias for `.middleware()`)
+   *
+   * Accepts both regular middleware handlers and named middlewares (NamedMiddleware).
+   * Named middlewares that are already registered globally will be automatically
+   * deduplicated to prevent double execution.
+   *
+   * @example
+   * ```ts
+   * import { authenticate } from '@spfn/auth/server/middleware';
+   *
+   * // With NamedMiddleware (auto-deduped if registered globally)
+   * route.get('/users')
+   *   .use([authenticate, RateLimitMiddleware()])
+   *
+   * // With regular middleware handlers
+   * route.get('/users')
+   *   .use([AuthMiddleware(), RateLimitMiddleware()])
+   * ```
+   */
+  use(middlewares) {
+    return this.middleware(middlewares);
+  }
+  /**
+   * Skip server-level named middlewares
+   *
+   * Useful for public endpoints that should bypass auth or rate limiting
+   *
+   * @param middlewareNames - Array of middleware names to skip, or '*' to skip all
+   *
+   * @example
+   * ```ts
+   * // Skip specific middlewares
+   * route.get('/status')
+   *   .skip(['auth', 'rateLimit'])
+   *   .handler(async (c) => c.json({ status: 'ok' }));
+   *
+   * // Skip only auth (still apply rate limiting)
+   * route.get('/public-data')
+   *   .skip(['auth'])
+   *   .handler(async (c) => { ... });
+   *
+   * // Skip all middlewares
+   * route.get('/public-health')
+   *   .skip('*')
+   *   .handler(async (c) => c.json({ status: 'ok' }));
+   * ```
+   */
+  skip(middlewareNames) {
+    return this.clone({ skipMiddlewares: middlewareNames });
+  }
+  /**
+   * Publish this route as a versioned contract operation
+   *
+   * Marks the route as a promise to clients that are compiled and deployed
+   * separately from the server — a mobile app, an external API consumer.
+   * The `@spfn/core:contract` generator writes every contracted route into
+   * `contracts/current.json`, and the build refuses a change that would break
+   * an already-released client.
+   *
+   * Routes without `.contract()` are unaffected: they simply do not appear in
+   * the contract. A web client needs nothing here — it derives its types from
+   * the router in the same build.
+   *
+   * @example
+   * ```ts
+   * export const getUser = route.get('/users/:id')
+   *   .input({ params: Type.Object({ id: Type.String() }) })
+   *   .contract({
+   *     since: '1.2.0',
+   *     auth: 'clientProofV1',
+   *     requiresSession: true,
+   *     response: Type.Object({
+   *       id: Type.String(),
+   *       name: Type.String(),
+   *       email: Type.Optional(Type.String()),
+   *     }),
+   *   })
+   *   .handler(async (c) => { ... });
+   * ```
+   */
+  contract(contract) {
+    return this.clone({ contract });
+  }
+  /**
+   * Define handler function
+   *
+   * Response type is automatically inferred from the return value.
+   * Use helper methods like `c.created()`, `c.paginated()` for proper type inference.
+   *
+   * @example
+   * ```ts
+   * // Direct return - type inferred from data
+   * route.get('/users/:id')
+   *   .input({ params: Type.Object({ id: Type.String() }) })
+   *   .handler(async (c) => {
+   *     const { params } = await c.data();
+   *     return await getUser(params.id); // Type: User
+   *   })
+   *
+   * // Using c.created() - returns data with 201 status, type preserved
+   * route.post('/users')
+   *   .input({ body: Type.Object({ name: Type.String() }) })
+   *   .handler(async (c) => {
+   *     const { body } = await c.data();
+   *     return c.created(await createUser(body)); // Type: User
+   *   })
+   *
+   * // Using c.paginated() - returns PaginatedResult<T>
+   * route.get('/users')
+   *   .handler(async (c) => {
+   *     const users = await getUsers();
+   *     return c.paginated(users, 1, 20, 100); // Type: PaginatedResult<User>
+   *   })
+   *
+   * // Using c.noContent() - returns void
+   * route.delete('/users/:id')
+   *   .handler(async (c) => {
+   *     await deleteUser(params.id);
+   *     return c.noContent(); // Type: void
+   *   })
+   *
+   * // Using c.json() - returns Response (type inference lost)
+   * // Use only when you need custom status codes not covered by helpers
+   * route.get('/custom')
+   *   .handler(async (c) => {
+   *     return c.json({ data }, 418); // Type: Response
+   *   })
+   * ```
+   */
+  handler(fn) {
+    return {
+      method: this._method,
+      path: this._path,
+      input: this._input,
+      interceptor: this._interceptor,
+      middlewares: this._middlewares,
+      skipMiddlewares: this._skipMiddlewares,
+      contract: this._contract,
+      handler: fn,
+      _input: {},
+      _interceptor: {},
+      _response: {}
+    };
+  }
+};
+function createMethodRoute(method) {
+  return (path) => {
+    const builder = new RouteBuilder();
+    builder._method = method;
+    builder._path = path;
+    return builder;
+  };
+}
+var route = {
+  get: createMethodRoute("GET"),
+  post: createMethodRoute("POST"),
+  put: createMethodRoute("PUT"),
+  patch: createMethodRoute("PATCH"),
+  delete: createMethodRoute("DELETE")
+};
+
+// src/route/router.ts
+function createRouterInstance(routes, packageRouters = [], globalMiddlewares = [], contractVersion = null) {
+  return {
+    routes,
+    _routes: routes,
+    _packageRouters: packageRouters,
+    _globalMiddlewares: globalMiddlewares,
+    _contractVersion: contractVersion,
+    packages(routers) {
+      const newPackageRouters = [...this._packageRouters, ...routers];
+      for (const pkgRouter of routers) {
+        if (pkgRouter._packageRouters?.length > 0) {
+          newPackageRouters.push(...pkgRouter._packageRouters);
+        }
+      }
+      return createRouterInstance(
+        this.routes,
+        newPackageRouters,
+        this._globalMiddlewares,
+        this._contractVersion
+      );
+    },
+    use(middlewares) {
+      return createRouterInstance(
+        this.routes,
+        this._packageRouters,
+        [...this._globalMiddlewares, ...middlewares],
+        this._contractVersion
+      );
+    },
+    contractVersion(version) {
+      assertContractVersion(version);
+      return createRouterInstance(
+        this.routes,
+        this._packageRouters,
+        this._globalMiddlewares,
+        version
+      );
+    }
+  };
+}
+function assertContractVersion(version) {
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)*$/.test(version)) {
+    throw new Error(
+      `contractVersion("${version}") is not a version of the form major.minor.patch. The released snapshot is named from this value and releases are compared by it.`
+    );
+  }
+}
+function defineRouter(routes) {
+  return createRouterInstance(routes);
+}
+
+// src/route/validation.ts
+FormatRegistry.Set(
+  "email",
+  (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+);
+FormatRegistry.Set(
+  "uri",
+  (value) => /^https?:\/\/.+/.test(value)
+);
+FormatRegistry.Set(
+  "uuid",
+  (value) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)
+);
+FormatRegistry.Set(
+  "date",
+  (value) => /^\d{4}-\d{2}-\d{2}$/.test(value)
+);
+FormatRegistry.Set(
+  "date-time",
+  (value) => !isNaN(Date.parse(value))
+);
+
+// src/server/server-time.ts
+var CORE_TIME_OPERATION_ID = "core.time";
+var ServerTimeResponseSchema = Type.Object({
+  serverTimeMillis: Type.Integer()
+}, { additionalProperties: false });
+var systemServerClock = {
+  now: () => Date.now()
+};
+function createCoreTimeRoute(clock = systemServerClock) {
+  return route.get(CORE_TIME_PATH).skip("*").contract({
+    since: "0.3.0",
+    auth: "none",
+    requiresSession: false,
+    response: ServerTimeResponseSchema
+  }).handler(async (c) => {
+    const response = {
+      serverTimeMillis: clock.now()
+    };
+    c.raw.header("Cache-Control", "no-store");
+    return response;
+  });
+}
+var CORE_TIME_ROUTE = createCoreTimeRoute();
+function createCoreTimeRouter(clock) {
+  return defineRouter({
+    [CORE_TIME_OPERATION_ID]: createCoreTimeRoute(clock)
+  });
+}
+
 // src/server/create-server.ts
 var rateLimitApplied = /* @__PURE__ */ new WeakSet();
 async function createServer(config) {
@@ -1522,6 +1919,7 @@ async function createAutoConfiguredApp(config) {
   applyDefaultMiddleware(app, config, enableLogger, enableCors);
   await applyProxyGuard(app, config);
   applyRateLimit(config);
+  registerCoreTimeEndpoint(app, config);
   if (Array.isArray(config?.use)) {
     config.use.forEach((mw) => app.use("*", mw));
   }
@@ -1571,7 +1969,7 @@ async function applyProxyGuard(app, config) {
       serverLogger.warn("Proxy-guard nonce: cache module unavailable \u2014 using in-memory store (single instance only)");
     }
   }
-  const autoSkip = [CORE_HEALTH_PATH, LEGACY_HEALTH_PATH];
+  const autoSkip = [CORE_HEALTH_PATH, CORE_TIME_PATH, LEGACY_HEALTH_PATH];
   if (config?.healthCheck?.path) {
     autoSkip.push(config.healthCheck.path);
   }
@@ -1628,6 +2026,10 @@ function resolveHealthCheck(config) {
     detailed: healthCheckConfig.detailed ?? process.env.NODE_ENV === "development"
   };
 }
+function registerCoreTimeEndpoint(app, config) {
+  registerRoutes(app, createCoreTimeRouter(config?.serverTime?.clock));
+  serverLogger.debug(`Server time endpoint enabled at ${CORE_TIME_PATH}`);
+}
 function registerCoreHealthEndpoint(app, config) {
   const { enabled, path, detailed } = resolveHealthCheck(config);
   if (!enabled) {
@@ -3231,6 +3633,15 @@ var ServerConfigBuilder = class {
     this.config.healthCheck = healthCheck;
     return this;
   }
+  /**
+   * Supply the clock used by the built-in `GET /_core/time` capability.
+   * Production servers normally keep the default `Date.now()` clock; this is
+   * exposed so tests can assert an exact wire value without replacing globals.
+   */
+  serverTime(serverTime) {
+    this.config.serverTime = serverTime;
+    return this;
+  }
   /**
    * Configure infrastructure initialization
    */
@@ -3327,6 +3738,6 @@ function defineServerConfig() {
   return new ServerConfigBuilder();
 }
 
-export { CORE_HEALTH_PATH, CORE_NAMESPACE, PendingMigrationsError, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnv, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };
+export { CORE_HEALTH_PATH, CORE_NAMESPACE, CORE_TIME_OPERATION_ID, CORE_TIME_PATH, CORE_TIME_ROUTE, PendingMigrationsError, ServerTimeResponseSchema, createCoreTimeRoute, createServer, createServerlessApp, defineServerConfig, getMigrationSnapshot, getShutdownManager, loadEnv, loadEnvFiles, provisionInfrastructure, resetMigrationSnapshot, resetServerlessApp, startServer };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map