@cosmicdrift/kumiko-framework 0.374.0 → 0.378.0

package/dist/files/file-ref-entity.d.ts

@@ -14,7 +14,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -37,7 +37,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -60,7 +60,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -95,7 +95,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -118,7 +118,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -141,7 +141,7 @@ export declare const fileRefEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {

package/dist/files/file-ref-table.d.ts

@@ -13,7 +13,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -36,7 +36,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -59,7 +59,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -94,7 +94,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -117,7 +117,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {
@@ -140,7 +140,7 @@ export declare const fileRefsTable: import("../db/table-builder.ts").EntityTable
         readonly sensitive?: boolean;
         readonly writeOnly?: boolean;
         readonly readAsInstruction?: boolean;
-        readonly format?: "email" | "url" | "phone" | "password";
+        readonly format?: "email" | "url" | "phone" | "password" | "month";
         readonly default?: string;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
         readonly multiline?: boolean | {

package/dist/files/index.d.ts

@@ -5,7 +5,7 @@ export { createFileRefFromBytes, createFileRefFromUploadedBytes, uploadFileBytes
 export { createFilesFeature, FILES_FEATURE } from "./feature.ts";
 export type { FileContext, FileHandle } from "./file-handle.ts";
 export { createFileContext, createTenantFileContext, deriveKey, storageKeyStemPrefix, } from "./file-handle.ts";
-export { fileRefEntity } from "./file-ref-entity.ts";
+export { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.ts";
 export { fileRefsTable } from "./file-ref-table.ts";
 export type { FileAccessDecision, FileAccessGuard, FileRef, FileRoutesOptions, } from "./file-routes.ts";
 export { createFileRoutes, readFilesRouteOptions, resolveMaxUploadBodyBytes, } from "./file-routes.ts";

package/dist/files/index.js

@@ -4,7 +4,7 @@ export { createFilesFeature, FILES_FEATURE } from "./feature.js";
 // `createFileHandle` is an implementation detail — construct handles via
 // `createFileContext(provider).ref(key)`, which is the AppContext surface.
 export { createFileContext, createTenantFileContext, deriveKey, storageKeyStemPrefix, } from "./file-handle.js";
-export { fileRefEntity } from "./file-ref-entity.js";
+export { FILE_REF_ENTITY_NAME, fileRefEntity } from "./file-ref-entity.js";
 export { fileRefsTable } from "./file-ref-table.js";
 export { createFileRoutes, readFilesRouteOptions, resolveMaxUploadBodyBytes, } from "./file-routes.js";
 export { createInMemoryFileProvider } from "./in-memory-provider.js";

package/dist/files/provider-resolver.d.ts

@@ -6,30 +6,30 @@ import type { ConfigAccessor, ConfigAccessorFactory, Registry } from "../engine/
 import type { SecretsContext } from "../secrets/index.ts";
 import type { FileStorageProvider } from "./types.ts";
 /**
- * Schmaler Surface-Type fuer Provider-Plugins. HandlerContext ist zu fett
- * (haelt tx, actor, signal etc.) — Provider sollen sich auf die read-Felder
- * beschraenken die fuer Tenant-Config + Secret-Lookup gebraucht werden.
+ * Narrow surface type for provider plugins. HandlerContext carries tx, actor,
+ * signal and more; providers only get the read fields needed for tenant config
+ * and secret lookup.
  *
- * **Warum nicht voller HandlerContext?** Im Worker-Pfad (r.job) gibt es keinen
- * request-bezogenen `tx`/`actor`/`signal`. Wenn ein Provider `ctx.tx` lesen
- * wuerde, wuerde der ganze Worker-Pfad zur Runtime brechen — und das wuerde NUR
- * mit S3 und nur in production auffallen. Die schmale Surface zwingt Provider
- * zur expliziten Erweiterung statt silent ctx-feld-ausnutzen.
+ * **Why not the full HandlerContext?** On the worker path (r.job) there is no
+ * request-bound `tx`/`actor`/`signal`. A provider reading `ctx.tx` would break
+ * the whole worker path at runtime, and that would only show up with S3 in
+ * production. The narrow surface forces providers to extend it explicitly
+ * instead of quietly relying on extra ctx fields.
  *
- * **Felder:**
- *   config  — fuer tenant-config-reads (bucket/region/endpoint/...)
- *   registry — fuer extension-Lookup in der Factory (nicht Plugin-intern)
- *   secrets — fuer tenant-secret-reads (s3.secretAccessKey)
- *   _userId — Audit-/Authority-Identity fuer secret-reads. Der Framework-
- *             Resolver setzt das auf SYSTEM_USER_ID — der s3-Provider liest
- *             `s3.secretAccessKey`, was Nicht-Admin-Request-User nicht duerfen;
- *             die Request-User-Autorisierung bleibt am Route-accessGuard.
+ * **Fields:**
+ *   config      — tenant config reads (bucket/region/endpoint/...)
+ *   registry    — extension lookup in the factory (not plugin-internal)
+ *   secrets     — tenant secret reads (s3.secretAccessKey)
+ *   auditUserId — audit and authority identity for secret reads. The framework
+ *                 resolver sets SYSTEM_USER_ID because the s3 provider reads
+ *                 `s3.secretAccessKey`, which non-admin request users may not;
+ *                 request-user authorization stays on the route accessGuard.
  */
 export type FileProviderContext = {
     readonly config?: ConfigAccessor;
     readonly registry?: Registry;
     readonly secrets?: SecretsContext;
-    readonly _userId?: string | undefined;
+    readonly auditUserId?: string | undefined;
 };
 /**
  * File-Storage-Plugin contract. Each provider-feature (file-provider-s3,

package/dist/files/provider-resolver.js

@@ -110,7 +110,7 @@ export function makeFileProviderResolver(deps) {
                 db: deps.db,
                 secrets: deps.secrets,
             });
-            return createFileProviderForTenant({ config, registry: deps.registry, secrets: deps.secrets, _userId: SYSTEM_USER_ID }, tenantId);
+            return createFileProviderForTenant({ config, registry: deps.registry, secrets: deps.secrets, auditUserId: SYSTEM_USER_ID }, tenantId);
         })();
         built.catch(() => {
             if (cache.get(tenantId) === built)

package/dist/http/egress.d.ts

@@ -0,0 +1,14 @@
+import { type EgressPolicy, type ResolvedHost } from "./policy.ts";
+type PinnedRequestInit = RequestInit & {
+    tls?: {
+        servername: string;
+    };
+};
+export declare function egress(policy: EgressPolicy): (raw: string, init?: RequestInit) => Promise<Response>;
+export declare function withOriginalUrl(res: Response, originalUrl: URL): Response;
+export declare function buildPinnedRequest(url: URL, resolved: ResolvedHost, init: RequestInit | undefined): {
+    url: URL;
+    init: PinnedRequestInit;
+};
+export declare function withManualRedirect(init: RequestInit | undefined): RequestInit;
+export {};

package/dist/http/egress.js

@@ -0,0 +1,144 @@
+import { assertAllowedTarget, assertHttpScheme, assertValidInternalPolicy, resolvePublicHost, } from "./policy.js";
+const MAX_INTERNAL_REDIRECTS = 5;
+// Single exported way to speak outward. The policy is named once, at bind
+// time, and cannot drift from the request that follows it.
+export function egress(policy) {
+    if (policy.kind === "internal")
+        assertValidInternalPolicy(policy);
+    return (raw, init) => runEgress(policy, raw, init);
+}
+async function runEgress(policy, raw, init) {
+    const url = new URL(raw);
+    assertHttpScheme(url);
+    if (policy.kind === "internal") {
+        assertAllowedTarget(url, policy);
+        return fetchWithAllowlistedRedirects(url, policy, init);
+    }
+    // external + tenant-supplied: deny private/reserved/link-local ranges,
+    // pin the connect to the exact address that passed that check (closes the
+    // DNS-rebinding TOCTOU, see buildPinnedRequest), and never follow a
+    // redirect — a 3xx could point anywhere, including back into the denied
+    // ranges above. The caller sees the 3xx response itself and, to follow it,
+    // is expected to call `egress()` again with the Location header — which
+    // re-runs this same resolve-and-pin check against the new host.
+    const resolved = await resolvePublicHost(url);
+    const pinned = buildPinnedRequest(url, resolved, init);
+    const res = await fetch(pinned.url, withManualRedirect(pinned.init));
+    return withOriginalUrl(res, url);
+}
+// fetch() reports `res.url` as the address it actually connected to — the
+// pinned IP literal, not the hostname the caller asked for. Left alone, a
+// caller resolving a relative Location header the normal way
+// (`new URL(location, res.url)`) would resolve it against the IP instead of
+// the original host, and the re-invoked egress() call would then pin and
+// SNI-validate against that IP, breaking virtual hosting and TLS for
+// essentially every real server. Overwriting `.url` back to the original
+// request URL keeps that caller pattern working exactly as it would without
+// IP pinning.
+export function withOriginalUrl(res, originalUrl) {
+    Object.defineProperty(res, "url", { value: originalUrl.toString(), configurable: true });
+    return res;
+}
+// Rewrites the request to connect directly to `resolved.address` — the
+// exact address `resolvePublicHost` just validated — instead of handing
+// `fetch()` the original hostname and letting it resolve again. That second
+// resolution is the DNS-rebinding window: fetch-by-IP removes it entirely,
+// since there is no hostname left for fetch to look up. The original
+// hostname is preserved in the Host header (virtual hosting) and in
+// `tls.servername` (TLS SNI, and certificate validation still checks the
+// real hostname — not the IP we dial).
+export function buildPinnedRequest(url, resolved, init) {
+    const pinnedHost = resolved.family === 6 ? `[${resolved.address}]` : resolved.address;
+    const pinnedUrl = new URL(url.toString());
+    pinnedUrl.hostname = pinnedHost;
+    if (pinnedUrl.hostname !== pinnedHost) {
+        // The WHATWG URL hostname setter silently no-ops on invalid input
+        // instead of throwing. If that ever happened here, the request would
+        // silently fall back to the original (unpinned) hostname — reopening
+        // the rebinding window this function exists to close. Fail loudly.
+        throw new Error(`egress: failed to pin connection to resolved address ${resolved.address}`);
+    }
+    const headers = new Headers(init?.headers);
+    headers.set("host", url.host);
+    const pinnedInit = { ...init, headers };
+    if (url.protocol === "https:") {
+        pinnedInit.tls = { servername: url.hostname };
+    }
+    return { url: pinnedUrl, init: pinnedInit };
+}
+// Applied last, after spreading the caller's `init` — a caller cannot
+// override the policy's redirect handling by passing its own `redirect`
+// option. Used by both the external/tenant-supplied fetch above and the
+// internal redirect loop below, so it is not part of the package's public
+// barrel (not re-exported from index.ts) but is a plain named export for
+// that shared use and for pinning the invariant directly in
+// ./__tests__/egress.test.ts.
+export function withManualRedirect(init) {
+    return { ...init, redirect: "manual" };
+}
+const ORIGIN_CHANGE_SAFE_HEADERS = new Set([
+    "content-type",
+    "accept",
+    "accept-encoding",
+    "accept-language",
+    "user-agent",
+]);
+// Allowlist, not denylist: any credential-bearing header we have not thought
+// of (x-api-key, custom tokens) must not follow a redirect to another origin.
+function stripToSafeHeaders(init) {
+    const kept = new Headers();
+    for (const [name, value] of new Headers(init?.headers)) {
+        if (ORIGIN_CHANGE_SAFE_HEADERS.has(name))
+            kept.set(name, value);
+    }
+    return { ...init, headers: kept };
+}
+// `internal` is the only kind that permits redirects (it is the only kind
+// with an allowlist to re-validate them against). Each hop's Location is
+// resolved, restricted to the current hop's host and checked against the
+// policy before it is followed, capped at MAX_INTERNAL_REDIRECTS.
+// `init` (method, body) is replayed verbatim on every hop — unlike a browser,
+// this does not downgrade POST to GET on a 301/302/303. Headers are replayed
+// only while the origin is unchanged; once a hop leaves the original origin
+// (scheme or port differs), credential headers are dropped for the rest of the
+// chain. The body is still replayed to the new origin (as fetch does on
+// 307/308); use allowOrigins to forbid such hops entirely.
+async function fetchWithAllowlistedRedirects(url, policy, init) {
+    let current = url;
+    let hopInit = init;
+    let strippedInit;
+    for (let hop = 0; hop <= MAX_INTERNAL_REDIRECTS; hop++) {
+        const res = await fetch(current, withManualRedirect(hopInit));
+        if (res.status < 300 || res.status >= 400)
+            return res;
+        const location = res.headers.get("location");
+        if (!location)
+            return res; // 3xx without Location — nothing to follow
+        let next;
+        try {
+            next = new URL(location, current);
+        }
+        catch {
+            throw new Error(`egress(internal): redirect Location header is not a resolvable URL: ${location}`);
+        }
+        assertHttpScheme(next);
+        // Hosts may differ in the allowlist; credentials must still not hop
+        // between them.
+        if (next.hostname.toLowerCase() !== current.hostname.toLowerCase()) {
+            throw new Error(`egress(internal): redirect crosses host (${current.hostname} -> ${next.hostname}), not followed`);
+        }
+        try {
+            assertAllowedTarget(next, policy);
+        }
+        catch {
+            // Prefix is the contract consumers match on (chat-webhook-sender); origins only, no path/query.
+            throw new Error(`egress(internal): redirect target not in allowlist (${current.origin} -> ${next.origin}), not followed`);
+        }
+        if (next.origin !== url.origin) {
+            strippedInit ??= stripToSafeHeaders(init);
+            hopInit = strippedInit;
+        }
+        current = next;
+    }
+    throw new Error(`egress(internal): exceeded ${MAX_INTERNAL_REDIRECTS} redirects`);
+}

package/dist/http/index.d.ts

@@ -1,2 +1,3 @@
-export type { EgressPolicy, ResolvedHost } from "@cosmicdrift/kumiko-http";
-export { BlockedHostError, buildPinnedRequest, egress, HostResolutionError, isPublicHost, resolvePublicHost, resolvePublicHostname, } from "@cosmicdrift/kumiko-http";
+export { buildPinnedRequest, egress } from "./egress.ts";
+export type { EgressPolicy, ResolvedHost } from "./policy.ts";
+export { BlockedHostError, HostResolutionError, isPublicHost, resolvePublicHost, resolvePublicHostname, } from "./policy.ts";

package/dist/http/index.js

@@ -1 +1,2 @@
-export { BlockedHostError, buildPinnedRequest, egress, HostResolutionError, isPublicHost, resolvePublicHost, resolvePublicHostname, } from "@cosmicdrift/kumiko-http";
+export { buildPinnedRequest, egress } from "./egress.js";
+export { BlockedHostError, HostResolutionError, isPublicHost, resolvePublicHost, resolvePublicHostname, } from "./policy.js";

package/dist/http/policy.d.ts

@@ -0,0 +1,30 @@
+import { lookup } from "node:dns/promises";
+export type EgressPolicy = {
+    readonly kind: "external";
+} | {
+    readonly kind: "internal";
+    readonly allowHosts?: readonly string[];
+    readonly allowOrigins?: readonly string[];
+} | {
+    readonly kind: "tenant-supplied";
+};
+export declare function isBlockedIp(ip: string): boolean;
+export declare function assertHttpScheme(url: URL): void;
+export interface ResolvedHost {
+    readonly address: string;
+    readonly family: 4 | 6;
+}
+export declare class BlockedHostError extends Error {
+    constructor(message: string);
+}
+export declare class HostResolutionError extends Error {
+    constructor(message: string);
+}
+export declare function resolvePublicHostname(rawHost: string, lookupFn?: typeof lookup): Promise<ResolvedHost>;
+export declare function resolvePublicHost(url: URL, lookupFn?: typeof lookup): Promise<ResolvedHost>;
+export declare function isPublicHost(raw: string, lookupFn?: typeof lookup): Promise<boolean>;
+export type InternalEgressPolicy = Extract<EgressPolicy, {
+    kind: "internal";
+}>;
+export declare function assertValidInternalPolicy(policy: InternalEgressPolicy): void;
+export declare function assertAllowedTarget(url: URL, policy: InternalEgressPolicy): void;