@cosmicdrift/kumiko-types 0.337.1 → 0.339.0

package/dist/config.d.ts

@@ -25,6 +25,14 @@ export type ConfigComputedContext = {
     readonly db: DbConnection | TenantDb;
 };
 export type ConfigComputedFn<T extends ConfigKeyType = ConfigKeyType> = (ctx: ConfigComputedContext) => Promise<ConfigValue<T>>;
+export type ConfigValidateContext = {
+    readonly key: string;
+    readonly scope: ConfigScope;
+    readonly tenantId: TenantId;
+    readonly userId: string | null;
+    readonly db: DbConnection | TenantDb;
+};
+export type ConfigValidateFn<T extends ConfigKeyType = ConfigKeyType> = (value: ConfigValue<T>, ctx: ConfigValidateContext) => Promise<void>;
 export type ConfigBacking = "config" | "secrets";
 export type ConfigSecretsReader = {
     get(tenantId: TenantId, key: string): Promise<{
@@ -60,6 +68,7 @@ export type ConfigKeyDefinition<T extends ConfigKeyType = ConfigKeyType> = {
         readonly flags?: string;
     };
     readonly computed?: ConfigComputedFn<T>;
+    readonly validate?: ConfigValidateFn<T>;
     readonly allowPerRequest?: boolean;
     readonly required?: boolean;
     readonly env?: string;

package/dist/define-handler.d.ts

@@ -12,6 +12,7 @@ export type WriteHandlerDefinition<TName extends string = string, TSchema extend
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;
     readonly escapeHatch?: EscapeHatchDeclaration;
+    readonly tenantlessAnonymous?: boolean;
     readonly handler: (event: WriteEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
     readonly perform?: PipelineDef<z.infer<TSchema>, TData>;
 };
@@ -24,6 +25,7 @@ export type WriteHandlerInput<TName extends string = string, TSchema extends Zod
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;
     readonly escapeHatch?: EscapeHatchDeclaration;
+    readonly tenantlessAnonymous?: boolean;
 } & ({
     readonly handler: (event: WriteEvent<z.infer<TSchema>>, context: HandlerContext<TMap>) => Promise<WriteResult<TData>>;
     readonly perform?: never;

package/dist/handlers.d.ts

@@ -28,9 +28,18 @@ export type RoleAccessRule = {
     readonly personalData?: RoleAccessPersonalData;
 };
 export type AccessRule = RoleAccessRule | OpenToAllAccessRule;
+export declare const ESCAPE_HATCH_GRANTS: readonly ["systemIdentity", "globalWrites", "unsafeRaw"];
+export type EscapeHatchGrant = (typeof ESCAPE_HATCH_GRANTS)[number];
 export type EscapeHatchDeclaration = {
     readonly reason: string;
-};
+    readonly grants?: readonly EscapeHatchGrant[];
+};
+export declare function isEscapeHatchGrant(value: unknown): value is EscapeHatchGrant;
+export declare function escapeHatchAllows(declaration: EscapeHatchDeclaration | undefined, grant: EscapeHatchGrant): boolean;
+export declare function escapeHatchFor(declaration: EscapeHatchDeclaration | undefined, grant: EscapeHatchGrant): EscapeHatchDeclaration | undefined;
+export declare function escapeHatchGrantsProblem(declaration: {
+    readonly grants?: unknown;
+}): string | undefined;
 export declare function isOpenToAllGranted(rule: AccessRule): boolean;
 export declare function isUiAccessGranted(access: AccessRule | undefined, userRoles: readonly string[] | undefined): boolean;
 export type SessionUserOrigin = "member-resolution";
@@ -149,6 +158,14 @@ type SharedContextFields = {
     readonly jobRunner?: JobRunnerRef;
     readonly configResolver?: ConfigResolver;
     readonly config?: ConfigAccessor;
+    /**
+     * Config accessor resolved for ANOTHER tenant, identity = that tenant's system
+     * user (the caller's user-scope config never leaks in). Cross-tenant calls
+     * throw AccessDeniedError unless the caller is a system identity or has the
+     * SystemAdmin role; the caller's own tenant needs no privilege. Present when
+     * the config feature wired its accessor factory.
+     */
+    readonly configFor?: (tenantId: TenantId) => ConfigAccessor;
     readonly _configAccessorFactory?: ConfigAccessorFactory;
     readonly configEncryption?: import("./envelope-cipher-types.js").EnvelopeCipher;
     readonly rateLimit?: import("./rate-limit-types.js").RateLimitResolver;
@@ -456,6 +473,10 @@ export type WriteHandlerDef = {
     readonly unsafeSkipTransitionGuard?: boolean;
     readonly rateLimit?: RateLimitDeclaration;
     readonly escapeHatch?: EscapeHatchDeclaration;
+    /** Lets an anonymous `POST /api/write` for this handler proceed under
+     *  SYSTEM_TENANT_ID when the host resolves no tenant. Boot requires
+     *  `access.roles: ["anonymous"]` and a real `rateLimit`. */
+    readonly tenantlessAnonymous?: boolean;
     readonly perform?: import("./step.js").PipelineDef;
 };
 export declare const ENTITY_CONVENTION_QUERY_BRAND = "__kumikoEntityConventionQuery";

package/dist/handlers.js

@@ -1,3 +1,31 @@
+export const ESCAPE_HATCH_GRANTS = ["systemIdentity", "globalWrites", "unsafeRaw"];
+export function isEscapeHatchGrant(value) {
+    return ESCAPE_HATCH_GRANTS.some((grant) => grant === value);
+}
+export function escapeHatchAllows(declaration, grant) {
+    if (declaration === undefined)
+        return false;
+    return declaration.grants === undefined || declaration.grants.includes(grant);
+}
+// Returns the declaration only when it unlocks `grant`, so call sites keep passing
+// "a declaration or nothing" into grant-gated code.
+export function escapeHatchFor(declaration, grant) {
+    return escapeHatchAllows(declaration, grant) ? declaration : undefined;
+}
+// Boot-time check of `grants` (untyped sources can carry anything): must be a non-empty list of known grants.
+export function escapeHatchGrantsProblem(declaration) {
+    const { grants } = declaration;
+    if (grants === undefined)
+        return undefined;
+    if (!Array.isArray(grants) || grants.length === 0) {
+        return `grants must be a non-empty list of: ${ESCAPE_HATCH_GRANTS.join(", ")}`;
+    }
+    const unknownGrant = grants.find((grant) => !isEscapeHatchGrant(grant));
+    if (unknownGrant !== undefined) {
+        return `unknown grant ${JSON.stringify(unknownGrant)} — allowed: ${ESCAPE_HATCH_GRANTS.join(", ")}`;
+    }
+    return undefined;
+}
 // AccessRule can arrive from untyped sources (pattern-library JSON, Designer)
 // where `openToAll` doesn't actually match the declared union — narrow via
 // `unknown` instead of trusting the static type, deny on anything malformed.

package/dist/tenant-db-types.d.ts

@@ -34,9 +34,9 @@ export type TenantDb = {
     readonly mode: TenantDbMode;
     /**
      * Unfiltered DbRunner escape hatch for handlers/hooks that declare `escapeHatch: { reason }`.
-     * Throws `AccessDeniedError` when ungranted, or `Error` when `reason` is empty.
+     * Throws `AccessDeniedError` when ungranted. The audit entry carries the declared escapeHatch reason.
      */
-    unsafeRaw(reason: string): DbRunner;
+    unsafeRaw(): DbRunner;
     /**
      * Reach a "global" table with the tenant filter lifted — reads always work; writes
      * reject unless the write handler declared `escapeHatch: { reason }`. "tenant"-tenancy is a compile error here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-types",
-  "version": "0.337.1",
+  "version": "0.339.0",
   "description": "Framework-Type-Definitions für Kumiko — FeatureDefinition, BootCheck-Types und die reinen Engine-Types. Erlaubt Downstream-Konsumenten, gegen die Type-Contracts zu bauen, ohne das ganze Framework-Package zu importieren. Enthaelt keine identitaets-sensitiven Runtime-Werte mehr (Error-Klassen leben seit #1629 in kumiko-framework, Brand-Symbole nutzen Symbol.for) und ist deshalb eine plain dependency, keine peerDependency.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "ctx.configFor on the handler context types",
+    "detail": "`configFor?: (tenantId: TenantId) => ConfigAccessor` is part of the shared handler context fields, optional like `config`.",
+    "migration": "No code change needed."
+  },
   {
     "version": "0.337.0",
     "type": "improvement",