@ultimat3/core 22.0.0 → 22.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "22.0.0",
+  "version": "22.1.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "22.0.0"
+    "@ultimat3/schema": "22.1.0"
   }
 }

package/src/index.ts

@@ -590,6 +590,11 @@ export { DEFAULT_ROLE, isRole, ROLE_INFO, ROLES, resolveRole } from './roles';
 export type { HydrateStrategy, OfflineStrategy, RenderMode } from './route-vocabulary';
 export { HYDRATE_STRATEGIES, OFFLINE_STRATEGIES, RENDER_MODES } from './route-vocabulary';
 export { safeUrl, URL_ATTRIBUTES } from './safe-url';
+export {
+  type OriginEvidence,
+  type OriginVerdict,
+  proveSameOrigin,
+} from './same-origin';
 export {
   defineService,
   installedServices,

package/src/metrics.ts

@@ -391,11 +391,10 @@ export function counter(name: string, options?: InstrumentOptions): Counter {
 export function gauge(name: string, options?: GaugeOptions): Gauge {
   const instrument = declare(name, 'gauge', options ?? {});
   return {
-    // The screen runs BEFORE the series is resolved, the order `counter.add` already had: a
-    // refused value must cost nothing, and `seriesFor` is not a read — it MINTS a series, one of
-    // a bounded number, keeps it for the life of the process and can trip the cardinality
-    // ceiling. `a.b += finite(…)` evaluates the reference first, so the two cannot be folded
-    // back into one expression.
+    // The screen runs BEFORE the series is resolved, as in `counter.add`: a refused value must
+    // cost nothing, and `seriesFor` MINTS a series — bounded in number, kept for the process's
+    // life, able to trip the cardinality ceiling. `a.b += finite(…)` evaluates the reference
+    // first, so the two cannot be folded into one expression.
     record(value, attributes = {}): void {
       if (!enabled) return;
       const observed = finite(name, value);
@@ -443,6 +442,10 @@ function pointsOf(instrument: Instrument): readonly MetricPoint[] {
       return [];
     }
   }
+  // Declared counter, no sample: 0, not absent (`rate()` needs a series) — until one exists.
+  const unsampled =
+    enabled && instrument.descriptor.kind === 'counter' && instrument.series.size === 0;
+  if (unsampled) return [{ attributes: {}, value: 0 }];
   return [...instrument.series.values()].map((series) =>
     instrument.descriptor.kind === 'histogram'
       ? {

package/src/same-origin.ts

@@ -0,0 +1,51 @@
+// Single responsibility: the one rule for "did this request carrying an AMBIENT credential come
+// from this app?" — `@ultimat3/http`'s CSRF check asks it of an unsafe write, and
+// `@ultimat3/realtime`'s sync node of a websocket upgrade. One rule, so a sibling origin cannot be
+// let in by one surface and refused by the other.
+
+/** The complete `Sec-Fetch-Site` vocabulary. Anything else was written by a non-browser. */
+const KNOWN_SITES = new Set(['same-origin', 'same-site', 'cross-site', 'none']);
+
+export interface OriginEvidence {
+  /** The origins this app is reached on. More than one when the scheme is not knowable here. */
+  readonly selfOrigins: readonly string[];
+  readonly origin: string | null;
+  readonly secFetchSite: string | null;
+  /** An EXACT allowance for a sibling origin — never a wildcard, never a suffix match. */
+  readonly listed: (origin: string) => boolean;
+  /** Where the operator adds an origin, named in the refusal: `http.cors.origins`, `SYNC_ORIGINS`. */
+  readonly listName: string;
+}
+
+export type OriginVerdict =
+  | { readonly ok: true }
+  /** Why it was refused, in terms the caller can act on. Never echoes a header verbatim. */
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * `sec-fetch-site` first because it is the browser's own answer and cannot be set by script;
+ * `Origin` second, so an app that lists a sibling origin keeps working. `same-site` is NOT proof:
+ * a sibling subdomain is same-site, and a `SameSite=Lax` cookie rides its requests. A request with
+ * neither header is refused — "we could not tell" is the case this exists for.
+ */
+export function proveSameOrigin(evidence: OriginEvidence): OriginVerdict {
+  const site = evidence.secFetchSite;
+  if (site === 'same-origin' || site === 'none') return { ok: true };
+  const origin = evidence.origin;
+  if (origin !== null && evidence.selfOrigins.includes(origin)) return { ok: true };
+  if (origin !== null && evidence.listed(origin)) return { ok: true };
+  // Only the four values a browser can send are quoted back. Anything else is a client that
+  // wrote the header itself, and echoing what it wrote is how a rejected value reaches the log
+  // store and the response body.
+  if (site !== null) {
+    const known = KNOWN_SITES.has(site) ? site : 'a value no browser sends';
+    return { ok: false, reason: `the request reported sec-fetch-site: ${known}` };
+  }
+  return {
+    ok: false,
+    reason:
+      origin === null
+        ? 'the request carried neither sec-fetch-site nor origin, so it cannot be shown to be same-origin'
+        : `the origin it declares is not this app and is not listed in ${evidence.listName}`,
+  };
+}