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

package/README.md

@@ -359,6 +359,39 @@ probe depends on, and a probe reaches it unauthenticated. An app with `src/serve
 
 ---
 
+## How does a client synchronize with the server clock?
+
+Call `GET /_core/time` before minting a timestamped proof. It is a built-in,
+unauthenticated and session-free operation registered before application middleware and
+routes:
+
+```json
+{ "serverTimeMillis": 1750000000123 }
+```
+
+The response is a closed contract: `serverTimeMillis` is an integer Unix epoch in
+milliseconds and no additional fields are declared. It always carries
+`Cache-Control: no-store`; a cached clock reading is not a synchronization point.
+
+The value is trustworthy only when the transport is trustworthy. Production clients must
+call the endpoint over HTTPS and validate the server certificate. The endpoint does not
+sign its response, compensate for network latency, choose an authentication skew margin,
+or define client retry and persistence policy — those belong to the consuming protocol.
+
+Tests can inject an exact clock without replacing global time:
+
+```typescript
+const app = await createServer(defineServerConfig()
+    .serverTime({ clock: { now: () => 1750000000123 } })
+    .build());
+```
+
+`CORE_TIME_ROUTE`, `CORE_TIME_PATH`, `ServerTimeResponseSchema` and the
+`ServerTimeResponse` type are exported from `@spfn/core/server` for separately deployed
+client-contract exporters to consume from the same wire definition.
+
+---
+
 ## Can I deploy this to Vercel?
 
 Yes, and it is a first-class target rather than a workaround. From your app:

package/dist/contract/index.d.ts

@@ -1,8 +1,9 @@
-import { R as Router } from '../router-Cy7rAfmj.js';
-import { C as ContractDocument, a as ContractViolation, b as ContractOperation, c as ContractSnapshot } from '../types-CfYVhIQ9.js';
-export { d as CompatibilityPolicy, e as ContractRequest, f as ContractViolationKind, J as JsonSchema } from '../types-CfYVhIQ9.js';
+import { R as Router } from '../router-DJdpwuB6.js';
+import { C as ContractDocument, a as ContractViolation, b as ContractOperation, c as ContractSnapshot } from '../types-ClQVomgV.js';
+export { d as CompatibilityPolicy, e as ContractRequest, f as ContractViolationKind, J as JsonSchema } from '../types-ClQVomgV.js';
 import '../define-middleware-CVKgqo8S.js';
 import 'hono';
+import '../route-builder-2ani2jEI.js';
 import '@sinclair/typebox';
 import 'hono/utils/http-status';
 import '../route/types.js';

package/dist/ops/index.d.ts

@@ -1,6 +1,7 @@
 import { a as NamedMiddleware } from '../define-middleware-CVKgqo8S.js';
-import { a as RouteDef, R as Router, b as RouteBuilder } from '../router-Cy7rAfmj.js';
-import { J as JsonSchema } from '../types-CfYVhIQ9.js';
+import { R as RouteDef, a as RouteBuilder } from '../route-builder-2ani2jEI.js';
+import { R as Router } from '../router-DJdpwuB6.js';
+import { J as JsonSchema } from '../types-ClQVomgV.js';
 import { HttpMethod } from '../route/types.js';
 import 'hono';
 import '@sinclair/typebox';

package/dist/route/index.d.ts

@@ -1,5 +1,7 @@
-import { a as RouteDef, R as Router } from '../router-Cy7rAfmj.js';
-export { M as MergedInput, P as PaginatedResult, c as RouteAuthProfile, d as RouteBuilderContext, e as RouteContract, f as RouteHandlerFn, g as RouteInput, h as defineRouter, r as route } from '../router-Cy7rAfmj.js';
+import { R as RouteDef } from '../route-builder-2ani2jEI.js';
+export { M as MergedInput, P as PaginatedResult, b as RouteAuthProfile, c as RouteBuilderContext, d as RouteContract, e as RouteHandlerFn, f as RouteInput, r as route } from '../route-builder-2ani2jEI.js';
+import { R as Router } from '../router-DJdpwuB6.js';
+export { d as defineRouter } from '../router-DJdpwuB6.js';
 import { Hono, MiddlewareHandler } from 'hono';
 import { HttpMethod } from './types.js';
 export { E as ExtractMiddlewareNames, a as NamedMiddleware, N as NamedMiddlewareFactory, d as defineMiddleware, b as defineMiddlewareFactory } from '../define-middleware-CVKgqo8S.js';

package/dist/{router-Cy7rAfmj.d.ts → route-builder-2ani2jEI.d.ts}

@@ -1,5 +1,5 @@
-import { a as NamedMiddleware } from './define-middleware-CVKgqo8S.js';
 import { Context, MiddlewareHandler } from 'hono';
+import { a as NamedMiddleware } from './define-middleware-CVKgqo8S.js';
 import { TSchema, Static } from '@sinclair/typebox';
 import { ContentfulStatusCode, RedirectStatusCode } from 'hono/utils/http-status';
 import { HttpMethod } from './route/types.js';
@@ -550,127 +550,4 @@ declare const route: {
     delete: (path: string) => RouteBuilder;
 };
 
-/**
- * Router Definition
- *
- * Provides router composition and middleware management
- */
-
-/**
- * Router definition - holds all routes
- */
-interface Router<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>> {
-    routes: TRoutes;
-    _routes: TRoutes;
-    _packageRouters: Router<any>[];
-    _globalMiddlewares: NamedMiddleware<string>[];
-    /** The contract version these routes publish, or null when uncontracted. */
-    _contractVersion: string | null;
-    /**
-     * Register package routers (type-hidden)
-     *
-     * Package routes are:
-     * - Recognized by RPC proxy and backend
-     * - NOT exposed in client types (use package's own API like authApi, cmsApi)
-     *
-     * @example
-     * ```ts
-     * import { authRouter } from '@spfn/auth/server';
-     * import { cmsAppRouter } from '@spfn/cms/server';
-     *
-     * export const appRouter = defineRouter({
-     *     getRoot,
-     *     getStatus,
-     * })
-     * .packages([authRouter, cmsAppRouter]);
-     *
-     * // Client usage:
-     * // api.getRoot.call({})     - app routes
-     * // authApi.login.call({})   - package API
-     * ```
-     */
-    packages(routers: Router<any>[]): Router<TRoutes>;
-    /**
-     * Register global middlewares
-     *
-     * Applied to all routes unless explicitly skipped via .skip()
-     *
-     * @example
-     * ```ts
-     * import { authMiddleware, loggingMiddleware } from './middlewares';
-     *
-     * export const appRouter = defineRouter({
-     *     getRoot,
-     *     getStatus,
-     * })
-     * .packages([authRouter])
-     * .use([authMiddleware, loggingMiddleware]);
-     * ```
-     */
-    use(middlewares: NamedMiddleware<string>[]): Router<TRoutes>;
-    /**
-     * Declare the contract version these routes publish.
-     *
-     * A client compiled against this server — a mobile app in a store — is
-     * generated from one version of the contract and cannot be updated when the
-     * server changes. The server announces this version on every response so
-     * that client can tell whether the two ends still agree.
-     *
-     * This is the version's source. A released snapshot is written to
-     * `contracts/released/<version>.json` from what is declared here, so the
-     * filename follows the code rather than the code having to be told what the
-     * filename said.
-     *
-     * Only a server with contracted routes needs it. Without it the contract
-     * generator still writes `current.json` and still runs the compatibility
-     * gate; what it cannot do is cut a release or announce a version.
-     *
-     * @example
-     * ```ts
-     * export const appRouter = defineRouter({ getRoot, listItems })
-     *     .contractVersion('1.2.0')
-     *     .packages([authRouter]);
-     * ```
-     */
-    contractVersion(version: string): Router<TRoutes>;
-}
-/**
- * Define a router with multiple routes (tRPC-style)
- *
- * Supports chainable API for packages and middlewares:
- *
- * @example
- * ```ts
- * // Basic usage
- * export const appRouter = defineRouter({
- *     getRoot,
- *     getStatus,
- *     listExamples,
- * });
- *
- * // With package routers (type-hidden)
- * export const appRouter = defineRouter({
- *     getRoot,
- *     getStatus,
- * })
- * .packages([authRouter, cmsAppRouter]);
- *
- * // With global middlewares
- * export const appRouter = defineRouter({
- *     getRoot,
- *     getStatus,
- * })
- * .packages([authRouter])
- * .use([authMiddleware, loggingMiddleware]);
- *
- * export type AppRouter = typeof appRouter;
- * ```
- *
- * Package routes:
- * - Recognized by RPC proxy and backend for routing
- * - NOT included in AppRouter type (use authApi, cmsApi instead)
- * - Prevents confusion between app API and package APIs
- */
-declare function defineRouter<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>>(routes: TRoutes): Router<TRoutes>;
-
-export { type MergedInput as M, type PaginatedResult as P, type Router as R, type RouteDef as a, RouteBuilder as b, type RouteAuthProfile as c, type RouteBuilderContext as d, type RouteContract as e, type RouteHandlerFn as f, type RouteInput as g, defineRouter as h, route as r };
+export { type MergedInput as M, type PaginatedResult as P, type RouteDef as R, RouteBuilder as a, type RouteAuthProfile as b, type RouteBuilderContext as c, type RouteContract as d, type RouteHandlerFn as e, type RouteInput as f, route as r };

package/dist/router-DJdpwuB6.d.ts

@@ -0,0 +1,127 @@
+import { a as NamedMiddleware } from './define-middleware-CVKgqo8S.js';
+import { R as RouteDef } from './route-builder-2ani2jEI.js';
+
+/**
+ * Router Definition
+ *
+ * Provides router composition and middleware management
+ */
+
+/**
+ * Router definition - holds all routes
+ */
+interface Router<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>> {
+    routes: TRoutes;
+    _routes: TRoutes;
+    _packageRouters: Router<any>[];
+    _globalMiddlewares: NamedMiddleware<string>[];
+    /** The contract version these routes publish, or null when uncontracted. */
+    _contractVersion: string | null;
+    /**
+     * Register package routers (type-hidden)
+     *
+     * Package routes are:
+     * - Recognized by RPC proxy and backend
+     * - NOT exposed in client types (use package's own API like authApi, cmsApi)
+     *
+     * @example
+     * ```ts
+     * import { authRouter } from '@spfn/auth/server';
+     * import { cmsAppRouter } from '@spfn/cms/server';
+     *
+     * export const appRouter = defineRouter({
+     *     getRoot,
+     *     getStatus,
+     * })
+     * .packages([authRouter, cmsAppRouter]);
+     *
+     * // Client usage:
+     * // api.getRoot.call({})     - app routes
+     * // authApi.login.call({})   - package API
+     * ```
+     */
+    packages(routers: Router<any>[]): Router<TRoutes>;
+    /**
+     * Register global middlewares
+     *
+     * Applied to all routes unless explicitly skipped via .skip()
+     *
+     * @example
+     * ```ts
+     * import { authMiddleware, loggingMiddleware } from './middlewares';
+     *
+     * export const appRouter = defineRouter({
+     *     getRoot,
+     *     getStatus,
+     * })
+     * .packages([authRouter])
+     * .use([authMiddleware, loggingMiddleware]);
+     * ```
+     */
+    use(middlewares: NamedMiddleware<string>[]): Router<TRoutes>;
+    /**
+     * Declare the contract version these routes publish.
+     *
+     * A client compiled against this server — a mobile app in a store — is
+     * generated from one version of the contract and cannot be updated when the
+     * server changes. The server announces this version on every response so
+     * that client can tell whether the two ends still agree.
+     *
+     * This is the version's source. A released snapshot is written to
+     * `contracts/released/<version>.json` from what is declared here, so the
+     * filename follows the code rather than the code having to be told what the
+     * filename said.
+     *
+     * Only a server with contracted routes needs it. Without it the contract
+     * generator still writes `current.json` and still runs the compatibility
+     * gate; what it cannot do is cut a release or announce a version.
+     *
+     * @example
+     * ```ts
+     * export const appRouter = defineRouter({ getRoot, listItems })
+     *     .contractVersion('1.2.0')
+     *     .packages([authRouter]);
+     * ```
+     */
+    contractVersion(version: string): Router<TRoutes>;
+}
+/**
+ * Define a router with multiple routes (tRPC-style)
+ *
+ * Supports chainable API for packages and middlewares:
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * export const appRouter = defineRouter({
+ *     getRoot,
+ *     getStatus,
+ *     listExamples,
+ * });
+ *
+ * // With package routers (type-hidden)
+ * export const appRouter = defineRouter({
+ *     getRoot,
+ *     getStatus,
+ * })
+ * .packages([authRouter, cmsAppRouter]);
+ *
+ * // With global middlewares
+ * export const appRouter = defineRouter({
+ *     getRoot,
+ *     getStatus,
+ * })
+ * .packages([authRouter])
+ * .use([authMiddleware, loggingMiddleware]);
+ *
+ * export type AppRouter = typeof appRouter;
+ * ```
+ *
+ * Package routes:
+ * - Recognized by RPC proxy and backend for routing
+ * - NOT included in AppRouter type (use authApi, cmsApi instead)
+ * - Prevents confusion between app API and package APIs
+ */
+declare function defineRouter<TRoutes extends Record<string, RouteDef<any, any, any> | Router<any>>>(routes: TRoutes): Router<TRoutes>;
+
+export { type Router as R, defineRouter as d };

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 };