@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/pipeline/system-identity-switch.js

@@ -0,0 +1,248 @@
+import { withSystemDbUnsafeRawGrant, withUnsafeRawGrant, } from "../db/tenant-db.js";
+import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user.js";
+import { AccessDeniedError, FrameworkReasons, InternalError } from "../errors/index.js";
+export function isSystemIdentity(user) {
+    return user.id === SYSTEM_USER_ID || user.roles.includes(SYSTEM_ROLE);
+}
+function hasSameClaims(caller, asUser) {
+    if (caller.claims === asUser.claims)
+        return true;
+    const callerClaims = caller.claims ?? {};
+    const asUserClaims = asUser.claims ?? {};
+    const keys = Object.keys(callerClaims);
+    if (keys.length !== Object.keys(asUserClaims).length)
+        return false;
+    return keys.every((key) => Object.hasOwn(asUserClaims, key) &&
+        JSON.stringify(callerClaims[key]) === JSON.stringify(asUserClaims[key]));
+}
+// claims drive ownership row filters and origin makes a ctx read-only, so both must match exactly.
+export function isSelfDelegation(caller, asUser) {
+    return (asUser.id === caller.id &&
+        asUser.tenantId === caller.tenantId &&
+        asUser.origin === caller.origin &&
+        asUser.roles.every((role) => caller.roles.includes(role)) &&
+        hasSameClaims(caller, asUser));
+}
+export function isIdentitySwitchAllowed(caller, asUser, hasGrant) {
+    if (hasGrant)
+        return true;
+    if (isSystemIdentity(asUser) || caller === undefined)
+        return false;
+    return isSelfDelegation(caller, asUser);
+}
+export function systemIdentitySwitchDenied(callerLabel) {
+    return new AccessDeniedError({
+        message: `${callerLabel} may not switch identity to SYSTEM — declare r.systemScope() or ` +
+            "escapeHatch: { reason } on it",
+        details: { reason: FrameworkReasons.systemIdentitySwitchDenied },
+    });
+}
+export function identitySwitchDenied(callerLabel, asUser) {
+    if (isSystemIdentity(asUser))
+        return systemIdentitySwitchDenied(callerLabel);
+    return new AccessDeniedError({
+        message: `${callerLabel} may only switch identity to its own caller (same user, tenant, claims and ` +
+            "a subset of its roles) — declare r.systemScope() or escapeHatch: { reason } on it",
+        details: { reason: FrameworkReasons.identitySwitchDenied },
+    });
+}
+export function unsafeAllTenantsDenied(callerLabel) {
+    return new AccessDeniedError({
+        message: `${callerLabel} may not call ctx.queryProjection(..., { unsafeAllTenants: true }) — declare ` +
+            "r.systemScope() or escapeHatch: { reason } on it",
+        details: { reason: FrameworkReasons.unsafeAllTenantsDenied },
+    });
+}
+// Reverse-lookup so withHookEscapeHatchGrant can re-gate the SAME ungated pair (and caller) under a narrower grant.
+const sourceByGated = new WeakMap();
+// Same idea, for ctx.queryAsMember — a single function rather than a pair.
+const ungatedMemberReaderByGated = new WeakMap();
+function reportGrantedSwitch(caller, asUser, hasGrant, audit) {
+    // skip: no audit wired, switch wasn't grant-gated, or grant carries no reason to report
+    if (!audit || !hasGrant || audit.reason === undefined)
+        return;
+    // skip: caller switching to themselves isn't a privilege escalation worth auditing
+    if (caller !== undefined && isSelfDelegation(caller, asUser))
+        return;
+    audit.report("identity-switch", audit.reason, { id: asUser.id, tenantId: asUser.tenantId });
+}
+export function createGatedIdentitySwitch(callerLabel, caller, hasGrant, ungated, audit) {
+    const queryAs = async (asUser, qn, payload) => {
+        if (!isIdentitySwitchAllowed(caller, asUser, hasGrant)) {
+            throw identitySwitchDenied(callerLabel, asUser);
+        }
+        reportGrantedSwitch(caller, asUser, hasGrant, audit);
+        return ungated.queryAs(asUser, qn, payload);
+    };
+    const writeAs = async (asUser, qn, payload) => {
+        if (!isIdentitySwitchAllowed(caller, asUser, hasGrant)) {
+            throw identitySwitchDenied(callerLabel, asUser);
+        }
+        reportGrantedSwitch(caller, asUser, hasGrant, audit);
+        return ungated.writeAs(asUser, qn, payload);
+    };
+    const gated = { queryAs, writeAs };
+    const source = { ungated, caller, report: audit?.report };
+    sourceByGated.set(queryAs, source);
+    sourceByGated.set(writeAs, source);
+    return gated;
+}
+// ctx.queryAsMember's gate: the caller never names the target identity up
+// front (it's resolved internally), so this is a flat allow/deny.
+export function createGatedMemberReader(callerLabel, allowSystemIdentity, ungated, audit) {
+    const gated = async (userId, qn, payload) => {
+        if (!allowSystemIdentity)
+            throw systemIdentitySwitchDenied(callerLabel);
+        if (audit?.reason !== undefined) {
+            audit.report("identity-switch", audit.reason, { id: userId, tenantId: audit.tenantId });
+        }
+        return ungated(userId, qn, payload);
+    };
+    ungatedMemberReaderByGated.set(gated, { ungated, audit });
+    return gated;
+}
+// Same idea, for ctx.queryProjection — a single function rather than a pair.
+const ungatedProjectionReaderByGated = new WeakMap();
+// ctx.queryProjection's gate: only { unsafeAllTenants: true } is grant-checked —
+// a plain call always passes through, tenant-scoped by the projection's own table.
+export function createGatedProjectionReader(callerLabel, hasGrant, ungated, audit) {
+    const gated = async (qualifiedName, options) => {
+        if (options?.unsafeAllTenants === true) {
+            if (!hasGrant)
+                throw unsafeAllTenantsDenied(callerLabel);
+            if (audit?.reason !== undefined) {
+                audit.report("unsafe-all-tenants", audit.reason);
+            }
+        }
+        return ungated(qualifiedName, options);
+    };
+    ungatedProjectionReaderByGated.set(gated, { ungated, report: audit?.report });
+    return gated;
+}
+function readIdentitySwitchFn(context, key) {
+    if (!(key in context))
+        return undefined;
+    const value = context[key];
+    return typeof value === "function" ? value : undefined; // @cast-boundary engine-bridge — checked via typeof above
+}
+// context's own keys only — never touch a property of the resolved value, which may be a Proxy that throws on any get.
+function readDbLikeValue(context, key) {
+    if (!(key in context))
+        return undefined;
+    const value = context[key];
+    return typeof value === "object" && value !== null ? value : undefined;
+}
+function unavailableIdentitySwitchFn(callerLabel, kind) {
+    return async () => {
+        throw new InternalError({
+            message: `${callerLabel}: this context has no ${kind} to switch identity with.`,
+        });
+    };
+}
+function deniedResolveActiveMembership(callerLabel) {
+    return async () => {
+        throw systemIdentitySwitchDenied(callerLabel);
+    };
+}
+// Fail-closed fallback for a ctx not built by the dispatcher bridge (unit-test stub, duplicated module instance).
+function fallbackUngatedIdentitySwitch(callerLabel, ctxQueryAs, ctxWriteAs) {
+    return {
+        queryAs: ctxQueryAs ?? unavailableIdentitySwitchFn(callerLabel, "queryAs"),
+        writeAs: ctxWriteAs ?? unavailableIdentitySwitchFn(callerLabel, "writeAs"),
+    };
+}
+// Only a dispatcher-registered gate names the caller; ctx.user is never trusted, and two
+// gates for different callers (a hand-mixed ctx) yield none, so only a grant passes.
+function resolveDispatcherCaller(querySource, writeSource) {
+    if (querySource && writeSource && querySource.caller !== writeSource.caller)
+        return undefined;
+    return (querySource ?? writeSource)?.caller;
+}
+// Resolved per function: a shared ungated pair would revive a member-resolution
+// ctx's deny-stubbed writeAs through its still-registered queryAs.
+function gatedIdentitySwitchFields(callerLabel, escapeHatch, ctxQueryAs, ctxWriteAs) {
+    if (!ctxQueryAs && !ctxWriteAs)
+        return {};
+    const querySource = ctxQueryAs && sourceByGated.get(ctxQueryAs);
+    const writeSource = ctxWriteAs && sourceByGated.get(ctxWriteAs);
+    const ungatedQueryAs = ctxQueryAs && (querySource?.ungated.queryAs ?? ctxQueryAs);
+    const ungatedWriteAs = ctxWriteAs && (writeSource?.ungated.writeAs ?? ctxWriteAs);
+    const ungated = fallbackUngatedIdentitySwitch(callerLabel, ungatedQueryAs, ungatedWriteAs);
+    const caller = resolveDispatcherCaller(querySource, writeSource);
+    const report = (querySource ?? writeSource)?.report;
+    const audit = report ? { reason: escapeHatch?.reason, report } : undefined;
+    const gated = createGatedIdentitySwitch(callerLabel, caller, escapeHatch !== undefined, ungated, audit);
+    return {
+        ...(ctxQueryAs && { queryAs: gated.queryAs }),
+        ...(ctxWriteAs && { writeAs: gated.writeAs }),
+    };
+}
+// Unlike ctx.resolveActiveMembership (deny-only), a hook's own escapeHatch
+// can grant queryAsMember even when the enclosing handler has none.
+function gatedMemberReaderField(callerLabel, escapeHatch, ctxQueryAsMember) {
+    if (!ctxQueryAsMember)
+        return {};
+    const source = ungatedMemberReaderByGated.get(ctxQueryAsMember);
+    const ungated = source?.ungated ?? ctxQueryAsMember;
+    const audit = source?.audit
+        ? { reason: escapeHatch?.reason, report: source.audit.report, tenantId: source.audit.tenantId }
+        : undefined;
+    return {
+        queryAsMember: createGatedMemberReader(callerLabel, escapeHatch !== undefined, ungated, audit),
+    };
+}
+// Re-gates ctx.queryProjection under the hook's own escapeHatch, same
+// re-gating rule as the other fields below — see withHookEscapeHatchGrant.
+function gatedProjectionReaderField(callerLabel, escapeHatch, ctxQueryProjection) {
+    if (!ctxQueryProjection)
+        return {};
+    const source = ungatedProjectionReaderByGated.get(ctxQueryProjection);
+    const ungated = source?.ungated ?? ctxQueryProjection;
+    const audit = source?.report ? { reason: escapeHatch?.reason, report: source.report } : undefined;
+    return {
+        queryProjection: createGatedProjectionReader(callerLabel, escapeHatch !== undefined, ungated, audit),
+    };
+}
+export function withHookEscapeHatchGrant(context, callerLabel, escapeHatch) {
+    const ctxQueryAs = readIdentitySwitchFn(context, "queryAs");
+    const ctxWriteAs = readIdentitySwitchFn(context, "writeAs");
+    const ctxResolveActiveMembership = readIdentitySwitchFn(context, "resolveActiveMembership");
+    const ctxQueryAsMember = readIdentitySwitchFn(context, "queryAsMember");
+    const ctxQueryProjection = readIdentitySwitchFn(context, "queryProjection");
+    const ctxDb = readDbLikeValue(context, "db");
+    const ctxDbOutsideTransaction = readDbLikeValue(context, "dbOutsideTransaction");
+    const ctxSystemDb = readDbLikeValue(context, "systemDb");
+    if (!ctxQueryAs &&
+        !ctxWriteAs &&
+        !ctxResolveActiveMembership &&
+        !ctxQueryAsMember &&
+        !ctxQueryProjection &&
+        !ctxDb &&
+        !ctxDbOutsideTransaction &&
+        !ctxSystemDb) {
+        return context;
+    }
+    return {
+        ...context,
+        ...gatedIdentitySwitchFields(callerLabel, escapeHatch, ctxQueryAs, ctxWriteAs),
+        ...(ctxResolveActiveMembership &&
+            escapeHatch === undefined && {
+            resolveActiveMembership: deniedResolveActiveMembership(callerLabel),
+        }),
+        ...gatedMemberReaderField(callerLabel, escapeHatch, ctxQueryAsMember),
+        ...gatedProjectionReaderField(callerLabel, escapeHatch, ctxQueryProjection),
+        // @cast-boundary engine-bridge — withUnsafeRawGrant passes non-TenantDb values (e.g. a guard Proxy) through unchanged.
+        ...(ctxDb && { db: withUnsafeRawGrant(ctxDb, escapeHatch) }),
+        ...(ctxDbOutsideTransaction && {
+            dbOutsideTransaction: withUnsafeRawGrant(ctxDbOutsideTransaction, escapeHatch),
+        }),
+        // @cast-boundary engine-bridge — withSystemDbUnsafeRawGrant passes non-UncheckedSystemDb values through unchanged.
+        ...(ctxSystemDb && {
+            systemDb: withSystemDbUnsafeRawGrant(ctxSystemDb, escapeHatch, callerLabel),
+        }),
+    };
+}
+// Re-gates a hook's own ctx.queryAs/ctx.writeAs/ctx.queryProjection/ctx.db/ctx.dbOutsideTransaction/ctx.systemDb instead of inheriting the handler's grant.
+export function bindHookEscapeHatchGrant(fn, label, escapeHatch) {
+    return ((payload, context) => fn(payload, withHookEscapeHatchGrant(context, label, escapeHatch))); // @cast-boundary engine-bridge — LifecycleHookFn union, same (payload, context) shape at runtime
+}

package/dist/pipeline/tenant-timezone-cache.d.ts

@@ -0,0 +1,17 @@
+import type { TenantId } from "../engine/types/identifiers.js";
+export type TenantTimezoneCacheOptions = {
+    readonly ttlMs?: number;
+    readonly maxEntries?: number;
+    readonly now?: () => number;
+};
+export type TenantTimezoneCacheEntry = {
+    readonly value: string | undefined;
+};
+export type TenantTimezoneCache = {
+    get(tenantId: TenantId): TenantTimezoneCacheEntry | undefined;
+    set(tenantId: TenantId, value: string | undefined): void;
+    invalidate(tenantId: TenantId): void;
+    clear(): void;
+    size(): number;
+};
+export declare function createTenantTimezoneCache(opts?: TenantTimezoneCacheOptions): TenantTimezoneCache;

package/dist/pipeline/tenant-timezone-cache.js

@@ -0,0 +1,55 @@
+// Per-dispatcher in-process cache for the resolved tenant:config:timezone
+// value (fw#2462). dispatch-shared.ts's buildHandlerContext resolves that
+// key on every dispatch to build ctx.tz — without a cache that's a config
+// SELECT (sometimes two, cascade + fallback) per request, often inside an
+// open write transaction. A tenant-keyed TTL cache removes the steady-state
+// cost; dispatch-write.ts invalidates entries synchronously on
+// config:write:set/reset for this key, so the TTL below only covers writes
+// that bypass that path (migrations, seeds, direct DB edits).
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_MAX_ENTRIES = 1000;
+export function createTenantTimezoneCache(opts = {}) {
+    const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+    const maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    const now = opts.now ?? (() => Date.now());
+    // Map insertion order doubles as LRU order: touch = delete+re-insert.
+    const entries = new Map();
+    function evictOldestIfFull() {
+        // skip: cache has room, nothing to evict
+        if (entries.size < maxEntries)
+            return;
+        const oldestKey = entries.keys().next().value;
+        // skip: defensive — only reachable if maxEntries is 0 (cache disabled) and entries is empty
+        if (oldestKey === undefined)
+            return;
+        entries.delete(oldestKey);
+    }
+    return {
+        get(tenantId) {
+            const hit = entries.get(tenantId);
+            if (!hit)
+                return undefined;
+            if (hit.expiresAt <= now()) {
+                entries.delete(tenantId);
+                return undefined;
+            }
+            entries.delete(tenantId);
+            entries.set(tenantId, hit);
+            return { value: hit.value };
+        },
+        set(tenantId, value) {
+            entries.delete(tenantId);
+            evictOldestIfFull();
+            entries.set(tenantId, { value, expiresAt: now() + ttlMs });
+        },
+        invalidate(tenantId) {
+            entries.delete(tenantId);
+        },
+        clear() {
+            entries.clear();
+        },
+        size() {
+            return entries.size;
+        },
+    };
+}

package/dist/pipeline/write-origin.d.ts

@@ -0,0 +1,10 @@
+import { isPersonalDataGated, type WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
+import { type PersonalDataGate } from "../db/tenant-db.js";
+import type { Registry, SessionUser } from "../engine/types/index.js";
+import { AccessDeniedError } from "../errors/index.js";
+export { isPersonalDataGated, type WriteOrigin };
+export declare function effectiveWriteOrigin(root: WriteOrigin, inherited?: WriteOrigin): WriteOrigin;
+export declare function parseWriteOrigin(value: unknown): WriteOrigin | undefined;
+export declare function rootWriteOrigin(registry: Registry, type: string, user: SessionUser): WriteOrigin;
+export declare function publicIntakeRequiredError(origin: WriteOrigin, target: string, fields: readonly string[]): AccessDeniedError;
+export declare function buildPersonalDataGate(registry: Registry, origin: WriteOrigin): PersonalDataGate | undefined;

package/dist/pipeline/write-origin.js

@@ -0,0 +1,110 @@
+// The static check in boot-validator/access-declarations.ts only sees a handler's own
+// input schema; writes reached via ctx.write/writeAs/queryAs, hooks or foreign-feature
+// tables are only visible at the actual write, so the gate runs there at runtime.
+import { isPersonalDataGated } from "@cosmicdrift/kumiko-types/event-store-types";
+import * as z from "zod";
+import { buildEntityTable } from "../db/table-builder.js";
+import { tableNameOf } from "../db/tenant-db.js";
+import { accessAllowsAnonymous, declaredPersonalData, personalFieldNames, } from "../engine/personal-data-fields.js";
+import { ANONYMOUS_ROLE } from "../engine/system-user.js";
+import { AccessDeniedError } from "../errors/index.js";
+import { FrameworkReasons } from "../errors/reasons.js";
+import { toSnakeCase } from "../utils/case.js";
+export { isPersonalDataGated };
+// Only narrows: an inherited origin can add a gate, never lift the root's.
+export function effectiveWriteOrigin(root, inherited) {
+    if (!inherited)
+        return root;
+    if (isPersonalDataGated(root))
+        return root;
+    if (isPersonalDataGated(inherited))
+        return inherited;
+    return root;
+}
+const writeOriginSchema = z
+    .object({
+    rootHandler: z.string(),
+    anonymousRoot: z.boolean(),
+    publicIntake: z.boolean(),
+    viaJob: z.string().optional(),
+})
+    .strict();
+export function parseWriteOrigin(value) {
+    const parsed = writeOriginSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+function declaresPublicIntake(access) {
+    return accessAllowsAnonymous(access) && declaredPersonalData(access) === "public-intake";
+}
+// Only the public dispatcher entry points compute a root; every nested call inherits
+// it, so switching identity via ctx.writeAs(SYSTEM, ...) cannot shed an anonymous root.
+export function rootWriteOrigin(registry, type, user) {
+    const writeHandler = registry.getWriteHandler(type);
+    return {
+        rootHandler: type,
+        anonymousRoot: user.roles.includes(ANONYMOUS_ROLE),
+        publicIntake: writeHandler !== undefined && declaresPublicIntake(writeHandler.access),
+    };
+}
+// Owner binding is ignored (honorOwnerBinding=false): all anonymous callers share one
+// user id, so from("user:id", ...) vouches for nobody.
+const personalDataTableMaps = new WeakMap();
+function personalColumnNames(entity) {
+    return new Set([...personalFieldNames(entity, false)].map(toSnakeCase));
+}
+function buildPersonalDataTableMap(registry) {
+    const map = new Map();
+    for (const [entityName, entity] of registry.getAllEntities()) {
+        const columns = personalColumnNames(entity);
+        if (columns.size === 0)
+            continue;
+        const table = buildEntityTable(entityName, entity, {
+            relations: registry.getRelations(entityName),
+        });
+        map.set(tableNameOf(table), columns);
+    }
+    return map;
+}
+function personalDataTableMap(registry) {
+    const cached = personalDataTableMaps.get(registry);
+    if (cached)
+        return cached;
+    const built = buildPersonalDataTableMap(registry);
+    personalDataTableMaps.set(registry, built);
+    return built;
+}
+// Names fields only, never values: the error reaches the anonymous HTTP caller.
+export function publicIntakeRequiredError(origin, target, fields) {
+    return new AccessDeniedError({
+        message: `Anonymous root handler "${origin.rootHandler}" wrote personal-data field(s) ` +
+            `${fields.map((f) => `"${f}"`).join(", ")} on "${target}"` +
+            (origin.viaJob ? ` via job "${origin.viaJob}"` : "") +
+            '. Declare access: { roles: [..., "anonymous"], personalData: "public-intake" } on ' +
+            `"${origin.rootHandler}" to allow anonymous callers to write personal data.`,
+        details: {
+            reason: FrameworkReasons.publicIntakeRequired,
+            rootHandler: origin.rootHandler,
+            target,
+            fields,
+            ...(origin.viaJob !== undefined && { job: origin.viaJob }),
+        },
+    });
+}
+// Without an entity the table name is looked up in the registry map; tables outside it
+// (unmanaged stores, hand-built tables) carry no personal-data annotations and pass.
+export function buildPersonalDataGate(registry, origin) {
+    if (!isPersonalDataGated(origin))
+        return undefined;
+    const map = personalDataTableMap(registry);
+    return (tableName, keys, entity) => {
+        const personalFields = entity ? personalColumnNames(entity) : map.get(tableName);
+        // skip: table carries no personal-data annotations
+        if (!personalFields)
+            return;
+        const offending = [...new Set(keys.map(toSnakeCase))].filter((k) => personalFields.has(k));
+        // skip: write touches no personal-data field
+        if (offending.length === 0)
+            return;
+        throw publicIntakeRequiredError(origin, tableName, offending);
+    };
+}

package/dist/random/generate.d.ts

@@ -0,0 +1,56 @@
+export type AdjNounNameOptions = {
+    /** Trennzeichen zwischen adj/noun (und ggf. suffix). Default "-". */
+    readonly separator?: string;
+    /** Wenn gesetzt, wird ein random-suffix der Länge .length angehängt
+     *  (no-confusable-Alphabet). Empfohlen 3 Zeichen = 32^3 = 32.768
+     *  zusätzliche Combinations pro Wortpaar. */
+    readonly suffix?: {
+        readonly length: number;
+    };
+    /** Custom Adjective-Liste — default ADJECTIVES (191 generic). */
+    readonly adjectives?: readonly string[];
+    /** Custom Noun-Liste — default NOUNS (173 generic). Apps die Domain-
+     *  spezifische Slugs wollen (z.B. webhook-feature mit eigenen
+     *  -receiver/-listener-Substantiven) reichen ihre eigene Liste. */
+    readonly nouns?: readonly string[];
+};
+/** Sync Generator: produziert "happy-cloud" oder "happy-cloud-k8x"
+ *  (mit suffix). Kein Conflict-Check — Caller verantwortlich für
+ *  Uniqueness, oder generateUniqueName() für die async Variante. */
+export declare function generateAdjNounName(options?: AdjNounNameOptions): string;
+/** Random-String aus dem no-confusable-Alphabet. Für Suffix-bei-Kollision
+ *  oder als standalone short-IDs (z.B. Webhook-Verifizierungs-Codes
+ *  zum Vorlesen am Telefon). length ≥ 1. */
+export declare function generateNoConfusableId(length: number): string;
+export type GenerateUniqueNameOptions = {
+    /** Caller-Predicate. Returns true wenn der Name noch nicht vergeben
+     *  ist (typisch: DB-Query "select where slug=$1" → row count === 0). */
+    readonly isAvailable: (name: string) => Promise<boolean>;
+    /** Max Versuche OHNE Suffix bevor wir auf suffix-mode wechseln.
+     *  Default 3. Bei 33.043 Default-Combos und ~150 existierenden
+     *  Tenants liegt p(Kollision) < 1% — 3 Versuche reichen weit. */
+    readonly maxCleanAttempts?: number;
+    /** Suffix-Länge bei Kollision-Mode. Default 3 (= 32.768 Combinations
+     *  pro Wortpaar). */
+    readonly suffixLength?: number;
+    /** Hard-Cap an Total-Versuchen bevor wir aufgeben. Default 20.
+     *  Praktisch nie erreicht — wenn doch, ist die Wortliste leer oder
+     *  isAvailable() returnt durchgängig false (DB-Bug). */
+    readonly maxTotalAttempts?: number;
+    readonly separator?: string;
+    readonly adjectives?: readonly string[];
+    readonly nouns?: readonly string[];
+};
+/** Generiert einen unique Adj-Noun-Slug indem es bis zu maxCleanAttempts
+ *  saubere Wortpaare versucht, danach mit random Suffix bis maxTotal-
+ *  Attempts. Wirft wenn auch das nicht hilft (= caller hat ein Bug
+ *  mit isAvailable, oder die Wortliste ist defekt).
+ *
+ *  Beispiel:
+ *    const slug = await generateUniqueName({
+ *      isAvailable: async (s) =>
+ *        !(await db.select().from(tenants).where(eq(tenants.tenantKey, s)).then(r => r.length > 0)),
+ *    });
+ *    // → "happy-cloud" oder "happy-cloud-k8x" bei Kollision
+ */
+export declare function generateUniqueName(options: GenerateUniqueNameOptions): Promise<string>;

package/dist/random/generate.js

@@ -0,0 +1,92 @@
+// Random-Generator für human-readable Resource-Identifier:
+//   - Tenant-Keys ("happy-cloud", "swift-river-k8x")
+//   - Webhook-Subscriber-Slugs ("bold-falcon-receiver" mit custom nouns)
+//   - API-Key-Display-Names (3 Vorschläge anbieten beim Create)
+//   - Tenant-Subdomain-Vorschläge im Subdomain-Setup-Screen
+//   - Test-Fixtures mit lesbaren Identifiern
+//
+// NICHT für Security-Token (CSRF, Session, API-Keys, OAuth-State,
+// Reset-Token). Math.random() ist nicht kryptografisch unvorhersagbar.
+// Authority-binding für Tenant-Keys läuft über JWT + DB-Lookup, nicht
+// über Slug-Geheimhaltung — der Slug darf erratbar sein.
+//
+// Universal-safe: Math.random() läuft in Bun, Node, Metro/RN, Expo-Web.
+// Keine node:crypto-Imports.
+import { ADJECTIVES, NOUNS } from "./words.js";
+// Alphabet ohne handgetippt verwechselbare Zeichen:
+//   - keine 0/O (Null vs Großbuchstabe O)
+//   - keine 1/l/I (Eins vs Kleinbuchstabe L vs Großbuchstabe I)
+// Resultat: 32 Zeichen, sicher beim Telefon-Buchstabieren UND beim
+// Mailtext-Copy-Paste in fremde Schriftarten.
+const NO_CONFUSABLE_ALPHABET = "23456789abcdefghjkmnpqrstuvwxyz";
+const NO_CONFUSABLE_CHARS = Object.freeze(NO_CONFUSABLE_ALPHABET.split(""));
+function pickRandom(arr) {
+    if (arr.length === 0) {
+        throw new Error("pickRandom: cannot pick from empty array");
+    }
+    const value = arr[Math.floor(Math.random() * arr.length)];
+    // Length-Check oben garantiert dass index in-range ist.
+    if (value === undefined) {
+        throw new Error("pickRandom: indexed value undefined (sparse array?)");
+    }
+    return value;
+}
+/** Sync Generator: produziert "happy-cloud" oder "happy-cloud-k8x"
+ *  (mit suffix). Kein Conflict-Check — Caller verantwortlich für
+ *  Uniqueness, oder generateUniqueName() für die async Variante. */
+export function generateAdjNounName(options = {}) {
+    const sep = options.separator ?? "-";
+    const adjs = options.adjectives ?? ADJECTIVES;
+    const nouns = options.nouns ?? NOUNS;
+    let name = `${pickRandom(adjs)}${sep}${pickRandom(nouns)}`;
+    if (options.suffix) {
+        name = `${name}${sep}${generateNoConfusableId(options.suffix.length)}`;
+    }
+    return name;
+}
+/** Random-String aus dem no-confusable-Alphabet. Für Suffix-bei-Kollision
+ *  oder als standalone short-IDs (z.B. Webhook-Verifizierungs-Codes
+ *  zum Vorlesen am Telefon). length ≥ 1. */
+export function generateNoConfusableId(length) {
+    if (length < 1) {
+        throw new Error(`generateNoConfusableId: length must be ≥ 1 (got ${length})`);
+    }
+    let id = "";
+    for (let i = 0; i < length; i++) {
+        id += pickRandom(NO_CONFUSABLE_CHARS);
+    }
+    return id;
+}
+/** Generiert einen unique Adj-Noun-Slug indem es bis zu maxCleanAttempts
+ *  saubere Wortpaare versucht, danach mit random Suffix bis maxTotal-
+ *  Attempts. Wirft wenn auch das nicht hilft (= caller hat ein Bug
+ *  mit isAvailable, oder die Wortliste ist defekt).
+ *
+ *  Beispiel:
+ *    const slug = await generateUniqueName({
+ *      isAvailable: async (s) =>
+ *        !(await db.select().from(tenants).where(eq(tenants.tenantKey, s)).then(r => r.length > 0)),
+ *    });
+ *    // → "happy-cloud" oder "happy-cloud-k8x" bei Kollision
+ */
+export async function generateUniqueName(options) {
+    const maxClean = options.maxCleanAttempts ?? 3;
+    const suffixLength = options.suffixLength ?? 3;
+    const maxTotal = options.maxTotalAttempts ?? 20;
+    if (maxClean > maxTotal) {
+        throw new Error(`generateUniqueName: maxCleanAttempts (${maxClean}) must not exceed maxTotalAttempts (${maxTotal})`);
+    }
+    const baseOptions = {
+        ...(options.separator !== undefined && { separator: options.separator }),
+        ...(options.adjectives !== undefined && { adjectives: options.adjectives }),
+        ...(options.nouns !== undefined && { nouns: options.nouns }),
+    };
+    for (let i = 0; i < maxTotal; i++) {
+        const useSuffix = i >= maxClean;
+        const name = generateAdjNounName(useSuffix ? { ...baseOptions, suffix: { length: suffixLength } } : baseOptions);
+        if (await options.isAvailable(name))
+            return name;
+    }
+    throw new Error(`generateUniqueName: failed to find available name after ${maxTotal} attempts. ` +
+        `Wordlists may be exhausted, or isAvailable() returns false unconditionally.`);
+}

package/dist/random/index.d.ts

@@ -0,0 +1,2 @@
+export { type AdjNounNameOptions, type GenerateUniqueNameOptions, generateAdjNounName, generateNoConfusableId, generateUniqueName, } from "./generate.js";
+export { ADJECTIVES, NOUNS } from "./words.js";

package/dist/random/index.js

@@ -0,0 +1,2 @@
+export { generateAdjNounName, generateNoConfusableId, generateUniqueName, } from "./generate.js";
+export { ADJECTIVES, NOUNS } from "./words.js";

package/dist/random/words.d.ts

@@ -0,0 +1,2 @@
+export declare const ADJECTIVES: readonly string[];
+export declare const NOUNS: readonly string[];