@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

package/dist/kernel/drain.js

@@ -0,0 +1,35 @@
+/** Request-time only: no Worker startup path imports this. */
+/** Read and discard what is left of a request body, at most 1 MiB and 1 s. A response sent over an unread POST body makes local
+ *  `wrangler dev` break the connection, and the next request fails with "Network connection lost". */
+async function drain(request) {
+    let reader;
+    const timer = setTimeout(() => reader?.cancel().catch(() => { }), 1000);
+    try {
+        reader = request.body?.getReader(); // a body the app consumed is done; one it still holds is locked and throws
+        for (let read = 0, chunk; reader && !(chunk = await reader.read()).done;)
+            if ((read += chunk.value.byteLength) > 1024 * 1024) {
+                await reader.cancel();
+                return;
+            }
+    }
+    catch { /* the client went away */ }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** A request handler that drains the body once it has answered or thrown. `undefined` and `null` mean the request is not this
+ *  handler's, so the next handler can still read it. A handler that answers and reads the request later (in `waitUntil`) must
+ *  read or lock the body before answering. */
+export const draining = (handle) => async (...args) => {
+    let response;
+    try {
+        response = await handle(...args);
+    }
+    catch (error) {
+        await drain(args[0]);
+        throw error;
+    }
+    if (response != null)
+        await drain(args[0]);
+    return response;
+};

package/dist/kernel/driver/bun-sqlite.d.ts

@@ -0,0 +1,19 @@
+/** `bun:sqlite`: sync queries; interactive transactions queue all work on the same Database. */
+import type { Bound } from "../binds.js";
+import { type Row } from "../contracts.js";
+export { definitive } from "../dialect/sqlite.js";
+export interface Handle {
+    query(sql: string): {
+        readonly columnNames: readonly string[];
+        all(...values: any[]): any[];
+        run(...values: any[]): {
+            readonly changes: number | bigint;
+        };
+    };
+    exec(sql: string): unknown;
+    transaction(fn: (db: any) => any): (db: any) => any;
+}
+export declare const read: (db: Handle, sql: string, binds: unknown[]) => any[] | Promise<any[]>;
+/** One statement is atomic on its own; several run in a transaction, and a row statement that does not change exactly one row rolls it back. A unique-index clash is CONFLICT. */
+export declare function procedure(db: Handle, steps: readonly Bound[], path: string): Promise<Row[][]>;
+export declare function transaction<T>(db: Handle, fn: (tx: Handle) => Promise<T>): Promise<T>;

package/dist/kernel/driver/bun-sqlite.js

@@ -0,0 +1,77 @@
+import { checkConflict, conflict, ContractError } from "../contracts.js";
+import { unique } from "../dialect/sqlite.js";
+export { definitive } from "../dialect/sqlite.js";
+import { context, guard } from "./transaction-context.js";
+const transactions = new WeakSet();
+const queues = new WeakMap();
+/** Only queued transactions make otherwise synchronous statements wait; a rejection cannot poison the queue. */
+function enqueue(db, fn) {
+    const result = (queues.get(db) ?? Promise.resolve()).then(fn);
+    const tail = result.then(() => { }, () => { });
+    queues.set(db, tail);
+    void tail.then(() => { if (queues.get(db) === tail)
+        queues.delete(db); });
+    return result;
+}
+const available = (db, fn) => { guard(db); return queues.has(db) ? enqueue(db, fn) : fn(); };
+export const read = (db, sql, binds) => available(db, () => db.query(sql).all(...binds));
+/** One statement is atomic on its own; several run in a transaction, and a row statement that does not change exactly one row rolls it back. A unique-index clash is CONFLICT. */
+export async function procedure(db, steps, path) {
+    const execute = (handle) => steps.map(s => {
+        const statement = handle.query(s.sql);
+        // a statement with columns (SELECT, RETURNING) gives rows, and their number is its affected count
+        let rows = [], changes;
+        try {
+            rows = statement.columnNames.length ? statement.all(...s.binds) : [];
+            if (statement.columnNames.length)
+                changes = rows.length;
+            else {
+                statement.run(...s.binds);
+                // Bun's run().changes includes FTS maintenance writes; SQLite changes() counts the authored statement only.
+                changes = s.row ? Number(handle.query("SELECT changes() AS n").all()[0].n) : 0;
+            }
+        }
+        catch (error) {
+            throw unique(error) ? conflict(path, true, error) : checkConflict(path, error) ?? error;
+        }
+        if (s.row && changes !== 1)
+            throw conflict(path, false);
+        return rows;
+    });
+    return available(db, () => transactions.has(db) || steps.length === 1 ? execute(db) : db.transaction(execute)(db));
+}
+export async function transaction(db, fn) {
+    guard(db);
+    if (transactions.has(db))
+        throw new Error("Nested transactions are not supported.");
+    return enqueue(db, async () => {
+        db.exec("BEGIN IMMEDIATE");
+        let active = true;
+        const tx = { query: sql => {
+                if (!active)
+                    throw new Error("Transaction has ended.");
+                return db.query(sql);
+            }, exec: db.exec.bind(db), transaction: db.transaction.bind(db) };
+        transactions.add(tx);
+        const state = { outer: db, handle: tx };
+        try {
+            const result = await context.run(state, () => fn(tx));
+            db.exec("COMMIT");
+            return result;
+        }
+        catch (error) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch (rollback) {
+                throw new ContractError("OUTCOME_UNKNOWN", "Rollback failed; reconcile before retrying.", "store/transaction", { cause: new AggregateError([error, rollback]) });
+            }
+            throw error;
+        }
+        finally {
+            active = false;
+            state.outer = undefined;
+            state.handle = undefined;
+        }
+    });
+}

package/dist/kernel/driver/d1.d.ts

@@ -0,0 +1,24 @@
+/** Cloudflare D1: no interactive transactions, so a Procedure is one `batch` whose row checks go through `_mantle_assert`. */
+import type { Bound } from "../binds.js";
+import { type Row } from "../contracts.js";
+export { definitive } from "../dialect/sqlite.js";
+interface Statement {
+    bind(...values: any[]): Statement;
+    all(): Promise<{
+        results: any[];
+        meta: {
+            changes: number;
+        };
+    }>;
+}
+export interface Reader {
+    prepare(sql: string): Statement;
+}
+export interface Handle extends Reader {
+    batch(statements: any[]): Promise<{
+        results: any[];
+    }[]>;
+}
+export declare const read: (db: Reader, sql: string, binds: unknown[]) => Promise<any[]>;
+/** The assert table's trigger aborts the whole batch with `CONFLICT op=<k>` when statement k did not change exactly one row. */
+export declare function procedure(db: Handle, steps: readonly Bound[], path: string): Promise<Row[][]>;

package/dist/kernel/driver/d1.js

@@ -0,0 +1,22 @@
+import { checkConflict, conflict } from "../contracts.js";
+import { unique } from "../dialect/sqlite.js";
+export { definitive } from "../dialect/sqlite.js";
+export const read = async (db, sql, binds) => (await db.prepare(sql).bind(...binds).all()).results;
+/** The assert table's trigger aborts the whole batch with `CONFLICT op=<k>` when statement k did not change exactly one row. */
+export async function procedure(db, steps, path) {
+    const batch = [], at = [];
+    steps.forEach((s, i) => {
+        at.push(batch.length);
+        batch.push(db.prepare(s.sql).bind(...s.binds));
+        if (s.row)
+            batch.push(db.prepare(`INSERT INTO _mantle_assert (op,ok) SELECT ${i}, changes() = 1`));
+    });
+    let out;
+    try {
+        out = await db.batch(batch);
+    }
+    catch (error) {
+        throw unique(error) ? conflict(path, true, error) : /CONFLICT op=\d/.test(String(error?.message)) ? conflict(path, false, error) : checkConflict(path, error) ?? error;
+    }
+    return at.map(i => out[i].results);
+}

package/dist/kernel/driver/postgres.d.ts

@@ -0,0 +1,25 @@
+/** Bun.SQL's PostgreSQL shape (`Postgres`); postgres.js satisfies it as it is. */
+import type { Bound } from "../binds.js";
+import type { TransactionOptions } from "../store.js";
+import { type Postgres, type PostgresResult, type Row, type Unsafe } from "../contracts.js";
+export declare const read: (db: Unsafe, sql: string, binds: unknown[]) => PromiseLike<PostgresResult>;
+export declare function run(db: Unsafe, sql: string, binds: unknown[]): Promise<{
+    rows: any[];
+    changes: number;
+}>;
+/** A structured server ErrorResponse proves rollback; missing evidence is uncertain. */
+export declare function definitive(error: unknown): boolean;
+/**
+ * The error to throw when a PostgreSQL write fails where it may already have committed (autocommit, or COMMIT).
+ * A server ErrorResponse (SQLSTATE + severity) outside connection/resource classes rolled back; anything else, such as a
+ * lost socket, is OUTCOME_UNKNOWN.
+ */
+export declare function postgresOutcome(error: unknown, path: string): unknown;
+/**
+ * One statement is atomic on its own (a row statement touches at most one row, so a failed count check changes nothing)
+ * and runs in autocommit. Several run in `begin(serializable)`: a failure before the callback returns was rolled back;
+ * only a failed COMMIT can leave the outcome unknown.
+ */
+export declare function procedure(db: Postgres, steps: readonly Bound[], path: string): Promise<Row[][]>;
+/** Shared BEGIN/COMMIT outcome handling for Procedures and interactive Store transactions. */
+export declare function transaction<T>(db: Postgres, fn: (tx: Postgres) => Promise<T>, options?: TransactionOptions, path?: string): Promise<T>;

package/dist/kernel/driver/postgres.js

@@ -0,0 +1,99 @@
+import { conflict, ContractError, schemaCheckFailed } from "../contracts.js";
+import { context, guard } from "./transaction-context.js";
+const transactions = new WeakSet();
+const ISOLATION = ["serializable", "repeatable read", "read committed", "read uncommitted"];
+export const read = (db, sql, binds) => { guard(db); return db.unsafe(sql, binds); };
+export async function run(db, sql, binds) {
+    const rows = await read(db, sql, binds);
+    return { rows, changes: Number(rows.count ?? 0) };
+}
+/** SQLSTATE of a server error: `errno` on Bun.SQL, `code` on postgres.js. */
+const sqlstate = (error) => { const e = error; return typeof e?.errno === "string" ? e.errno : e?.code; };
+const check = (path, e) => schemaCheckFailed(path, e, e.table ?? e.table_name, e.constraint ?? e.constraint_name);
+/** A structured server ErrorResponse proves rollback; missing evidence is uncertain. */
+export function definitive(error) {
+    if (error instanceof ContractError)
+        return error.code === "CONFLICT";
+    const state = sqlstate(error);
+    return typeof state === "string" && /^[0-9A-Z]{5}$/.test(state) && typeof error?.severity === "string" && !/^(08|28|53|57|58|XX)/.test(state);
+}
+/**
+ * The error to throw when a PostgreSQL write fails where it may already have committed (autocommit, or COMMIT).
+ * A server ErrorResponse (SQLSTATE + severity) outside connection/resource classes rolled back; anything else, such as a
+ * lost socket, is OUTCOME_UNKNOWN.
+ */
+export function postgresOutcome(error, path) {
+    if (definitive(error))
+        return error;
+    return new ContractError("OUTCOME_UNKNOWN", "The write outcome is unknown; reconcile before retrying.", path, { cause: error });
+}
+/**
+ * One statement is atomic on its own (a row statement touches at most one row, so a failed count check changes nothing)
+ * and runs in autocommit. Several run in `begin(serializable)`: a failure before the callback returns was rolled back;
+ * only a failed COMMIT can leave the outcome unknown.
+ */
+export async function procedure(db, steps, path) {
+    const execute = async (handle) => {
+        const results = [];
+        for (const s of steps) {
+            const { rows, changes } = await run(handle, s.sql, s.binds).catch(error => { throw sqlstate(error) === "23505" ? conflict(path, true, error) : sqlstate(error) === "23514" ? check(path, error) : error; });
+            if (s.row && changes !== 1)
+                throw conflict(path, false);
+            results.push(rows);
+        }
+        return results;
+    };
+    if (transactions.has(db))
+        return execute(db);
+    if (steps.length === 1) {
+        try {
+            return await execute(db);
+        }
+        catch (error) {
+            throw error instanceof ContractError ? error : postgresOutcome(error, path);
+        }
+    }
+    return transaction(db, execute, undefined, path);
+}
+/** Shared BEGIN/COMMIT outcome handling for Procedures and interactive Store transactions. */
+export async function transaction(db, fn, options = {}, path = "store/transaction") {
+    guard(db);
+    if (transactions.has(db))
+        throw new Error("Nested transactions are not supported.");
+    // a transaction handle the app opened (postgres.js types it without `begin`) only suits reads and single statements
+    if (typeof db.begin !== "function")
+        throw new Error("This PostgreSQL handle is a transaction the app opened and cannot begin another: open the transaction with store(pool, caller).transaction and call Procedures through its tx.");
+    let committing = false;
+    const state = { outer: db };
+    try {
+        // printed into BEGIN, so only PostgreSQL's own four levels: a handler may pass request input here
+        const level = options.isolation ?? "serializable";
+        if (!ISOLATION.includes(level))
+            throw new ContractError("INPUT_VALIDATION_FAILED", `isolation '${level}' is not a PostgreSQL isolation level`, path);
+        return await db.begin(`isolation level ${level}`, async (handle) => {
+            let active = true;
+            const tx = { unsafe: (sql, values) => {
+                    if (!active)
+                        throw new Error("Transaction has ended.");
+                    return handle.unsafe(sql, values);
+                }, begin: async () => { throw new Error("Nested transactions are not supported."); } };
+            transactions.add(tx);
+            state.handle = tx;
+            try {
+                const result = await context.run(state, () => fn(tx));
+                committing = true;
+                return result;
+            }
+            finally {
+                active = false;
+            }
+        });
+    }
+    catch (error) {
+        throw error instanceof ContractError || !committing ? error : postgresOutcome(error, path);
+    }
+    finally {
+        state.outer = undefined;
+        state.handle = undefined;
+    }
+}

package/dist/kernel/driver/transaction-context.d.ts

@@ -0,0 +1,10 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export declare const context: AsyncLocalStorage<{
+    outer?: object;
+    handle?: object;
+    changes?: Map<string, number>;
+    parents?: Map<string, number>;
+}>;
+export declare function guard(db: object): void;
+/** One atomic write cannot publish a translation and change its parent's status. */
+export declare function translationWrite(db: object, schema: string, parent?: string): () => void;

package/dist/kernel/driver/transaction-context.js

@@ -0,0 +1,29 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { ContractError } from "../contracts.js";
+export const context = new AsyncLocalStorage();
+export function guard(db) {
+    if (context.getStore()?.outer === db)
+        throw new ContractError("INPUT_VALIDATION_FAILED", "Inside store.transaction use tx, not the outer store or handle.", "store/transaction");
+}
+/** One atomic write cannot publish a translation and change its parent's status. */
+export function translationWrite(db, schema, parent) {
+    const state = context.getStore();
+    if (!state || state.handle !== db)
+        return () => { };
+    schema = schema.toLowerCase();
+    parent = parent?.toLowerCase();
+    if (state.parents?.has(schema) || parent && state.changes?.has(parent))
+        throw new ContractError("INPUT_VALIDATION_FAILED", "Publish the translation and change its parent status in separate writes.", "translations");
+    const changes = state.changes ??= new Map(), parents = state.parents ??= new Map();
+    changes.set(schema, (changes.get(schema) ?? 0) + 1);
+    if (parent)
+        parents.set(parent, (parents.get(parent) ?? 0) + 1);
+    return () => { for (const [map, key] of [[changes, schema], [parents, parent]])
+        if (key) {
+            const count = map.get(key) - 1;
+            if (count)
+                map.set(key, count);
+            else
+                map.delete(key);
+        } };
+}

package/dist/kernel/email.d.ts

@@ -0,0 +1,28 @@
+/** The transactional-email port (Better Auth email OTP and magic link, admin invitations). The sender decides how to branch on `locale`; `category` names the template lane. */
+export interface EmailSender {
+    send(args: EmailSendArgs): Promise<void>;
+}
+export interface EmailSendArgs {
+    readonly to: string;
+    readonly subject: string;
+    /** Plain-text body — always required so non-HTML clients work. */
+    readonly text: string;
+    /** Optional HTML body. */
+    readonly html?: string;
+    /** BCP 47 locale the recipient is expected to read. */
+    readonly locale: string;
+    /** Optional categorization for templating / deliverability segmentation. */
+    readonly category?: string;
+}
+type EmailContent = Pick<EmailSendArgs, "subject" | "text">;
+export declare function signInCodeEmail(code: string): EmailContent;
+export declare function signInLinkEmail(url: string): EmailContent;
+export declare function adminInvitationEmail(role: string, signInUrl: string): EmailContent;
+/**
+ * Local development only: logs recipients and sign-in secrets, sends nothing.
+ * Select at the application's environment boundary; never use in production.
+ */
+export declare class ConsoleEmailSender implements EmailSender {
+    send(args: EmailSendArgs): Promise<void>;
+}
+export {};

package/dist/kernel/email.js

@@ -0,0 +1,38 @@
+function englishEmail(subject, lines) {
+    return {
+        subject,
+        text: `${lines.join("\n\n")}\n\nIf you did not expect this email, you can ignore it.`,
+    };
+}
+export function signInCodeEmail(code) {
+    return englishEmail(`Your Mantle sign-in code: ${code}`, [
+        `Your one-time code is ${code}.`,
+        "It expires shortly.",
+    ]);
+}
+export function signInLinkEmail(url) {
+    return englishEmail("Your Mantle sign-in link", [
+        "Use this link to sign in:",
+        url,
+        "The link expires shortly.",
+    ]);
+}
+export function adminInvitationEmail(role, signInUrl) {
+    return englishEmail("You have been invited to Mantle", [
+        `You now have ${role} access to Mantle.`,
+        "Sign in with this email address to accept the invitation:",
+        signInUrl,
+    ]);
+}
+/**
+ * Local development only: logs recipients and sign-in secrets, sends nothing.
+ * Select at the application's environment boundary; never use in production.
+ */
+export class ConsoleEmailSender {
+    async send(args) {
+        const { to, subject, text, locale, category } = args;
+        console.log(`[ConsoleEmailSender] ${category ?? "email"} → ${to} (${locale})\n` +
+            `  subject: ${subject}\n` +
+            `  body: ${text}`);
+    }
+}

package/dist/kernel/host-access.d.ts

@@ -0,0 +1,10 @@
+/** Request-only gateway decisions and observation; no database or compiler dependencies. */
+import { type AccessEvent, type Caller, type GatewayOptions, type RequestContext } from "./contracts.js";
+export declare function accessRequest(ctx: RequestContext | undefined, options: GatewayOptions): {
+    readonly dryRun: boolean;
+    select(target: string, resolved?: Caller): Promise<void>;
+    check(readOnly: boolean, variant?: string): Promise<void>;
+    finish(error?: unknown): AccessEvent;
+    finishResponse(response: Response): Promise<AccessEvent>;
+    response(): Response;
+};

package/dist/kernel/host-access.js

@@ -0,0 +1,65 @@
+/** Request-only gateway decisions and observation; no database or compiler dependencies. */
+import { forwarded, ContractError, wire } from "./contracts.js";
+import { isHostCaller, checkFresh } from "./caller-identity.js";
+const logged = new WeakSet();
+export function accessRequest(ctx, options) {
+    const present = forwarded(ctx);
+    const props = ctx?.props?.mantle;
+    let caller, id = "", meta, finished;
+    let targets;
+    const fail = (code, status, field) => { throw new ContractError(code, code, id, { status, fields: field ? { field } : undefined }); };
+    return {
+        get dryRun() { return !!caller && isHostCaller(caller) && "dryRun" in caller && caller.dryRun === true; },
+        async select(target, resolved) {
+            id = target;
+            caller = resolved;
+            const all = await (targets ??= options.accessTargets?.());
+            meta = all && Object.hasOwn(all, id) ? all[id] : undefined;
+        },
+        async check(readOnly, variant) {
+            if (!caller || !isHostCaller(caller))
+                return;
+            const c = caller;
+            if (c.target !== undefined && c.target !== id)
+                fail("TARGET_MISMATCH", 412);
+            if (c.targetHash !== undefined && (!meta || c.targetHash !== meta.targetHash))
+                fail("TARGET_HASH_MISMATCH", 412);
+            checkFresh(caller, readOnly, id);
+            const policy = variant ? meta?.variants?.find(v => v.id === variant) ?? meta : meta;
+            if (this.dryRun && (!policy || policy.opaque || policy.guard))
+                fail("DRY_RUN_UNSUPPORTED", 412);
+        },
+        finish(error) {
+            if (finished)
+                return finished;
+            const failure = error === undefined ? undefined : wire(error);
+            finished = { v: 1, requestId: caller && "requestId" in caller ? caller.requestId ?? "" : typeof props?.requestId === "string" ? props.requestId : "", target: id, targetHash: meta?.targetHash ?? "",
+                caller: { kind: caller?.kind ?? (props?.layer === "member" ? "user" : "host"), subject: caller && "subject" in caller ? caller.subject : typeof props?.user === "object" && props.user && typeof props.user.id === "string" ? (props.layer === "admin" ? "host:" : "") + props.user.id : "", layer: caller && isHostCaller(caller) ? caller.kind === "host" ? "admin" : "member" : props?.layer === "member" ? "member" : "admin" },
+                outcome: failure ? [401, 403].includes(failure.status) ? "deny" : "error" : "allow", ...(failure ? { reason: failure.status === 401 ? "AUTH_DENIED" : failure.error.code, ...(typeof failure.error.field === "string" ? { field: failure.error.field } : {}) } : {}), dryRun: caller && isHostCaller(caller) ? this.dryRun : props?.dryRun === true };
+            finished = Object.freeze({ ...finished, caller: Object.freeze(finished.caller) });
+            if (present && options.onAccess) {
+                const listener = options.onAccess;
+                const log = () => { if (!logged.has(listener)) {
+                    logged.add(listener);
+                    console.error("[mantle onAccess] listener failed");
+                } };
+                // Schedule observation after the decision without awaiting its promise.
+                queueMicrotask(() => { try {
+                    void Promise.resolve(listener(finished)).catch(log);
+                }
+                catch {
+                    log();
+                } });
+            }
+            return finished;
+        },
+        async finishResponse(response) {
+            if (response.status < 400)
+                return this.finish();
+            const payload = await response.clone().json().catch(() => null);
+            const code = typeof payload?.error?.code === "string" ? payload.error.code : [401, 403].includes(response.status) ? "AUTH_DENIED" : response.status < 500 ? "INPUT_VALIDATION_FAILED" : "INTERNAL_ERROR";
+            return this.finish(new ContractError(code, "", id, { status: response.status, fields: payload?.error?.field ? { field: payload.error.field } : undefined }));
+        },
+        response() { return Response.json({ dryRun: true, event: this.finish() }, { headers: { "cache-control": "private, no-store" } }); },
+    };
+}

package/dist/kernel/host-caller.d.ts

@@ -0,0 +1,39 @@
+/** Request-only host contract validation. */
+export { draining } from "./drain.js";
+import { type Caller, type Gateway, type RequestContext } from "./contracts.js";
+import type { UserFields, UserValue } from "./user-fields.js";
+/** The complete JSON supplied as ctx.props.mantle by a trusted gateway. */
+export interface HostProps {
+    readonly v: 1;
+    readonly tenant: string;
+    readonly layer: "admin" | "member";
+    readonly user: Readonly<Record<string, UserValue>> & {
+        readonly id: string;
+        readonly role?: string;
+    };
+    readonly authenticatedAs: "snapshot" | "fresh";
+    readonly credential: "session" | "oauth";
+    readonly requestId: string;
+    /** Forwarded target pinning. */
+    readonly target?: string;
+    readonly targetHash?: string;
+    readonly dryRun?: boolean;
+}
+export type HostCaller = Extract<Caller, {
+    kind: "user" | "host";
+}> & {
+    readonly authenticatedAs: HostProps["authenticatedAs"];
+    readonly credential: HostProps["credential"];
+    readonly requestId: string;
+};
+/** Validate the forwarding contract and reuse the ordinary user validation and brand. */
+export declare function hostCaller(props: unknown, options: {
+    readonly tenant: string;
+    readonly fields?: UserFields;
+}): HostCaller;
+/** Resolve only forwarded props, or trip on an entry that did not opt in. */
+export declare function gatewayCaller(ctx: RequestContext | undefined, gateway: Gateway | undefined, fields?: UserFields): Caller;
+/** Host errors are machine-readable and never challenge for application credentials. */
+export declare function hostFailure(error: unknown, caller?: Caller, where?: string, challenge?: string): Response;
+export { isHostCaller } from "./caller-identity.js";
+export { checkFresh } from "./caller-identity.js";

package/dist/kernel/host-caller.js

@@ -0,0 +1,56 @@
+/** Request-only host contract validation. */
+export { draining } from "./drain.js";
+import { forwarded, ContractError, surfaceError, surfaceFailure } from "./contracts.js";
+import { userCaller } from "./user-caller.js";
+import { identities, isHostCaller } from "./caller-identity.js";
+const hostContract = (message, field) => { throw new ContractError("HOST_CONTRACT", message, "", { status: 412, fields: field ? { field } : undefined }); };
+/** Validate the forwarding contract and reuse the ordinary user validation and brand. */
+export function hostCaller(props, options) {
+    const record = (v) => !!v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+    const text = (v) => typeof v === "string" && v.length > 0 && !v.includes("\0") && v.isWellFormed();
+    if (!record(props))
+        return hostContract("Expected host contract v1.");
+    const keys = "v tenant layer user authenticatedAs credential requestId target targetHash dryRun".split(" ");
+    if (Object.keys(props).some(key => !keys.includes(key)) || props.v !== 1 || !text(props.tenant) || props.tenant !== options.tenant || !["admin", "member"].includes(props.layer) || !["snapshot", "fresh"].includes(props.authenticatedAs) || !["session", "oauth"].includes(props.credential) || !text(props.requestId) || !record(props.user))
+        return hostContract("Malformed host contract or tenant mismatch.");
+    for (const key of ["target", "targetHash"])
+        if (Object.hasOwn(props, key) && !text(props[key]))
+            return hostContract(`Invalid '${key}'.`, key);
+    if (Object.hasOwn(props, "dryRun") && typeof props.dryRun !== "boolean")
+        return hostContract("Invalid 'dryRun'.", "dryRun");
+    for (const key of ["target", "targetHash"])
+        if (props.layer === "admin" && !text(props[key]))
+            return hostContract(`Admin callers require '${key}'.`, key);
+    const user = props.user;
+    if (!text(user.id))
+        return hostContract("Invalid user id.", "id");
+    let base;
+    try {
+        base = userCaller(user, { fields: options.fields, adminRoles: [], credential: props.credential });
+    }
+    catch (error) {
+        return hostContract(error.message);
+    }
+    const caller = Object.freeze({ ...base, kind: props.layer === "admin" ? "host" : "user", subject: props.layer === "admin" ? "host:" + base.subject : base.subject, admin: props.layer === "admin", authenticatedAs: props.authenticatedAs, credential: props.credential, requestId: props.requestId, target: props.target, targetHash: props.targetHash, dryRun: props.dryRun === true });
+    identities.set(caller, Object.freeze({ ...identities.get(base), admin: caller.admin, host: true }));
+    return caller;
+}
+/** Resolve only forwarded props, or trip on an entry that did not opt in. */
+export function gatewayCaller(ctx, gateway, fields) {
+    const present = forwarded(ctx);
+    if (!gateway)
+        throw new ContractError('HOST_CONTRACT', 'Host props require gateway mode.', '', { status: 412 });
+    if (!present)
+        return { kind: 'anonymous' };
+    return hostCaller(ctx.props.mantle, { tenant: gateway.tenant, fields });
+}
+/** Host errors are machine-readable and never challenge for application credentials. */
+export function hostFailure(error, caller, where, challenge) {
+    if ((!caller || !isHostCaller(caller)) && !(error instanceof ContractError && error.code === 'HOST_CONTRACT'))
+        return surfaceFailure(error, challenge, where);
+    const result = surfaceError(error, where);
+    const code = result.status === 401 ? 'AUTH_DENIED' : result.error.code;
+    return Response.json({ error: { code, ...(typeof result.error.field === 'string' ? { field: result.error.field } : {}), ...(result.error.path ? { target: result.error.path } : {}) } }, { status: result.status === 401 ? 403 : result.status, headers: { 'cache-control': 'private, no-store' } });
+}
+export { isHostCaller } from "./caller-identity.js";
+export { checkFresh } from "./caller-identity.js";

package/dist/kernel/json-body.d.ts

@@ -0,0 +1,4 @@
+/** Request-only JSON reader: bound bytes before copying or parsing, independent of UTF-8 chunk boundaries. */
+/** Bound raw bytes before decoding a request body. */
+export declare function bytes(request: Request, limit: number, fail: (message: string) => never): Promise<Uint8Array>;
+export declare function body(request: Request, limit: number, fail: (message: string) => never): Promise<Record<string, unknown>>;

package/dist/kernel/json-body.js

@@ -0,0 +1,44 @@
+/** Request-only JSON reader: bound bytes before copying or parsing, independent of UTF-8 chunk boundaries. */
+/** Bound raw bytes before decoding a request body. */
+export async function bytes(request, limit, fail) {
+    if (!Number.isSafeInteger(limit) || limit < 1)
+        fail("Body limit must be a positive safe integer.");
+    const reader = request.body?.getReader();
+    let bytes = new Uint8Array(0), length = 0;
+    try {
+        while (reader) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            const end = length + value.byteLength;
+            if (end > limit) {
+                await reader.cancel().catch(() => { });
+                fail(`Request body exceeds ${limit} bytes.`);
+            }
+            if (end > bytes.length) {
+                const grown = new Uint8Array(Math.max(end, Math.min(limit, Math.max(1024, bytes.length * 2))));
+                grown.set(bytes);
+                bytes = grown;
+            }
+            bytes.set(value, length);
+            length = end;
+        }
+    }
+    finally {
+        reader?.releaseLock();
+    }
+    return bytes.subarray(0, length);
+}
+export async function body(request, limit, fail) {
+    const raw = await bytes(request, limit, fail);
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder().decode(raw).trim() || "{}");
+    }
+    catch {
+        fail("Expected a JSON body.");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail("Expected a JSON object.");
+    return value;
+}