@browserlessapi/inferlo 0.4.0 → 0.6.0

package/dist/openapi.js

@@ -1,3 +1,5 @@
+/** OpenAPI 3.1 document generated from routes. Served at /openapi.json by default. */
+import { describeDeprecation, resolveDeprecation } from "./deprecation.js";
 import { toolName } from "./mcp.js";
 const errorSchema = {
     type: "object",
@@ -18,7 +20,9 @@ const errorSchema = {
 };
 export function buildOpenAPI(app, options) {
     const paths = {};
-    for (const route of app.routes) {
+    // A version's document has its routes and the routes outside every version.
+    const routes = options.version === undefined ? app.routes : app.routes.filter((r) => r.version === undefined || r.version === options.version);
+    for (const route of routes) {
         const o = route.options;
         const openPath = route.path.replace(/:([^/]+)/g, "{$1}").replace(/\/\*$/, "/{wildcard}");
         const parameters = [];
@@ -38,20 +42,26 @@ export function buildOpenAPI(app, options) {
             operationId: route.name ?? toolName(route),
             summary: o.summary,
             description: o.description,
-            tags: o.tags,
+            // Routes of a feature module are tagged with its name unless they set their own tags.
+            tags: o.tags ?? (options.modules?.routeModule.has(route) ? [options.modules.routeModule.get(route)] : undefined),
             parameters: parameters.length ? parameters : undefined,
             requestBody: o.body ? { required: !o.body.def.optional, content: { "application/json": { schema: o.body.toJSONSchema() } } } : undefined,
             responses: {
                 "200": { description: "Success", content: o.response ? { "application/json": { schema: o.response.toJSONSchema() } } : undefined },
                 ...(o.body || o.query || o.params ? { "422": { description: "Validation failed (IL1001)", content: { "application/json": { schema: errorSchema } } } } : {}),
                 ...(!isPublic ? { "401": { description: "Sign in required (IL3001)", content: { "application/json": { schema: errorSchema } } } } : {}),
+                ...(o.permission ? { "403": { description: `Needs the "${o.permission}" permission (IL3004)`, content: { "application/json": { schema: errorSchema } } } } : {}),
                 ...(o.rateLimit
                     ? { "429": { description: `Too many requests (IL2005): ${o.rateLimit.max} per ${o.rateLimit.per} per ${o.rateLimit.by ?? "user"}`, content: { "application/json": { schema: errorSchema } } } }
                     : {}),
             },
             security: !isPublic && options.auth ? [{ bearerAuth: [] }] : undefined,
             "x-inferlo-auth": o.auth ?? "user",
+            "x-inferlo-permission": o.permission,
+            "x-inferlo-cache": o.cache ? { ttlMs: o.cache.ttlMs, by: o.cache.by ?? "user", tags: [...(o.cache.tags ?? [])] } : undefined,
             "x-inferlo-tool": o.tool ? toolName(route) : undefined,
+            deprecated: o.deprecated ? true : undefined,
+            "x-inferlo-deprecation": typeof o.deprecated === "object" ? describeDeprecation(resolveDeprecation(o.deprecated, `${route.method} ${route.path}`)) : undefined,
         };
         for (const key of Object.keys(operation))
             if (operation[key] === undefined)
@@ -63,7 +73,10 @@ export function buildOpenAPI(app, options) {
         schemas[m.name] = m.row.toJSONSchema();
     return {
         openapi: "3.1.0",
-        info: { title: app.name, version: app.version, description: options.description },
+        info: { title: app.name, version: app.version, description: options.description, ...(options.version ? { "x-inferlo-api-version": options.version } : {}) },
+        ...(options.modules?.modules.length
+            ? { tags: options.modules.modules.map((m) => (m.description ? { name: m.name, description: m.description } : { name: m.name })) }
+            : {}),
         paths,
         components: {
             schemas: { ...schemas, Error: errorSchema },

package/dist/openapi.js.map

@@ -1 +1 @@
-{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"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"}

package/dist/permissions.d.ts

@@ -0,0 +1,26 @@
+import type { AppUser } from "./route.ts";
+/** A rule: a function of the user (and the resources it needs) that returns true to allow, or the roles that may. */
+export type PermissionRule = ((input: any) => boolean | Promise<boolean>) | {
+    readonly roles: readonly string[];
+};
+/** What can() and authorize() take for a rule: the function's input, or { user } for a roles rule. */
+export type PermissionInput<R> = R extends (input: infer I) => unknown ? I : {
+    user: AppUser | null | undefined;
+};
+export interface Permissions<Rules extends Record<string, PermissionRule> = Record<string, PermissionRule>> {
+    readonly kind: "inferlo.permissions";
+    /** Every permission with its roles, for roles rules (shown in describe). */
+    readonly list: readonly {
+        readonly name: string;
+        readonly roles?: readonly string[];
+    }[];
+    /** True when the rule allows it. Never throws for a denial; a missing user is always denied. */
+    can<K extends keyof Rules & string>(name: K, input: PermissionInput<Rules[K]>): Promise<boolean>;
+    /** Resolves when the rule allows it; throws IL3001 (401) without a user and IL3004 (403) otherwise. */
+    authorize<K extends keyof Rules & string>(name: K, input: PermissionInput<Rules[K]>): Promise<void>;
+    /** True when the permission exists. */
+    has(name: string): boolean;
+}
+/** Define the app's permissions by name. Pass the result to createApp({ permissions }) to use route permission options. */
+export declare function permissions<const Rules extends Record<string, PermissionRule>>(rules: Rules): Permissions<Rules>;
+export declare function isPermissions(value: unknown): value is Permissions;

package/dist/permissions.js

@@ -0,0 +1,78 @@
+/**
+ * Named permissions, checked the same way in routes, AI tools and jobs:
+ *
+ *   export const access = permissions({
+ *     "reports.view": { roles: ["admin", "analyst"] },
+ *     "tickets.update": ({ user, ticket }: { user: AppUser; ticket: Row<typeof Ticket> }) =>
+ *       ticket.ownerId === user.id || (user.roles ?? []).includes("admin"),
+ *   });
+ *
+ *   await access.can("tickets.update", { user, ticket })        // true or false
+ *   await access.authorize("tickets.update", { user, ticket })  // throws IL3004 (403) when not allowed
+ *   route.get("/reports", { permission: "reports.view" })       // checked before the handler runs
+ *
+ * Deny by default: a missing user, an unknown permission or a rule that does not return true never allows.
+ */
+import { InferloError } from "./errors.js";
+const fix = 'Define each permission as a function that returns true or false, or as { roles: ["admin"] }: permissions({ "tickets.update": ({ user, ticket }) => ticket.ownerId === user.id }).';
+function invalid(message) {
+    return new InferloError("IL6026", message, { fix });
+}
+/** Define the app's permissions by name. Pass the result to createApp({ permissions }) to use route permission options. */
+export function permissions(rules) {
+    if (!rules || typeof rules !== "object" || Array.isArray(rules))
+        throw invalid("permissions() takes an object of named rules.");
+    const table = new Map();
+    const list = [];
+    for (const [name, rule] of Object.entries(rules)) {
+        if (!/^[A-Za-z][\w-]*(\.[\w-]+)*$/.test(name))
+            throw invalid(`Invalid permission name "${name}". Use names like "tickets.update".`);
+        if (typeof rule === "function") {
+            table.set(name, rule);
+            list.push({ name });
+            continue;
+        }
+        const roles = rule?.roles;
+        const keys = rule && typeof rule === "object" ? Object.keys(rule) : [];
+        if (!Array.isArray(roles) || roles.length === 0 || roles.some((r) => typeof r !== "string" || r === "") || keys.some((k) => k !== "roles")) {
+            throw invalid(`Invalid rule for permission "${name}".`);
+        }
+        const frozen = Object.freeze([...roles]);
+        table.set(name, { roles: frozen });
+        list.push(Object.freeze({ name, roles: frozen }));
+    }
+    const check = async (name, input) => {
+        const rule = table.get(name);
+        if (!rule)
+            throw invalid(`Unknown permission "${name}". Defined: ${[...table.keys()].join(", ") || "none"}.`);
+        const user = input?.user;
+        if (!user)
+            return false;
+        if (typeof rule !== "function") {
+            const roles = user.roles;
+            return Array.isArray(roles) && rule.roles.some((role) => roles.includes(role));
+        }
+        const allowed = await rule(input);
+        if (typeof allowed !== "boolean")
+            throw invalid(`The rule for permission "${name}" returned ${allowed === undefined ? "undefined" : typeof allowed} instead of true or false.`);
+        return allowed;
+    };
+    return Object.freeze({
+        kind: "inferlo.permissions",
+        list: Object.freeze(list),
+        can: (name, input) => check(name, input),
+        async authorize(name, input) {
+            if (await check(name, input))
+                return;
+            if (!input?.user) {
+                throw new InferloError("IL3001", "Sign in required.", { status: 401, fix: "Send valid credentials, e.g. an Authorization: Bearer <token> header." });
+            }
+            throw new InferloError("IL3004", `You do not have the "${name}" permission.`, { status: 403, fix: "Sign in as a user the permission allows, or ask an administrator for access." });
+        },
+        has: (name) => table.has(name),
+    });
+}
+export function isPermissions(value) {
+    return typeof value === "object" && value !== null && value.kind === "inferlo.permissions";
+}
+//# sourceMappingURL=permissions.js.map

package/dist/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"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"}

package/dist/react-router.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Inferlo inside React Router 7 and 8 (framework mode, formerly Remix) resource routes, without a runtime
+ * dependency on React Router:
+ *
+ *   // app/routes.ts: route("api/*", "routes/api.ts")
+ *   // app/routes/api.ts
+ *   import { toReactRouterHandlers } from "@browserlessapi/inferlo/react-router";
+ *   import { app } from "~/inferlo/app.server";
+ *
+ *   export const { loader, action } = toReactRouterHandlers(app, { prefix: "/api" });
+ *
+ * GET and HEAD requests reach the loader, POST, PUT, PATCH and DELETE the action; both run the whole Inferlo app.
+ * In other loaders and actions, use @browserlessapi/inferlo/ai. It never loads the router, database or jobs code.
+ */
+import type { App } from "./app.ts";
+/** The parts of React Router's loader and action arguments Inferlo uses. */
+export interface ReactRouterArgsLike {
+    /** The incoming Web request. */
+    request: Request;
+}
+/** A React Router loader or action that answers with the Inferlo app's Response. */
+export type ReactRouterHandler = (args: ReactRouterArgsLike) => Promise<Response>;
+/** The loader and action of a resource route: export const { loader, action } = toReactRouterHandlers(app). */
+export interface ReactRouterHandlers {
+    /** GET and HEAD requests. */
+    loader: ReactRouterHandler;
+    /** POST, PUT, PATCH and DELETE requests. */
+    action: ReactRouterHandler;
+}
+export interface ReactRouterHandlersOptions {
+    /**
+     * The URL path of the splat route, removed before the app routes the request: "/api" for route("api/*", ...).
+     * Requests outside it keep their path. Include the app's basename if one is set.
+     */
+    prefix?: string;
+}
+/**
+ * A loader and an action that run a whole Inferlo app (routes, auth, validation, rate limits, OpenAPI and MCP)
+ * from a React Router resource route.
+ */
+export declare function toReactRouterHandlers(app: Pick<App<any>, "fetch">, options?: ReactRouterHandlersOptions): ReactRouterHandlers;

package/dist/react-router.js

@@ -0,0 +1,42 @@
+import { InferloError } from "./errors.js";
+import { normalizePrefix, stripPrefix } from "./serve.js";
+const fix = 'Pass the app from createApp and the route\'s path: export const { loader, action } = toReactRouterHandlers(app, { prefix: "/api" }).';
+/**
+ * A loader and an action that run a whole Inferlo app (routes, auth, validation, rate limits, OpenAPI and MCP)
+ * from a React Router resource route.
+ */
+export function toReactRouterHandlers(app, options = {}) {
+    if (!app || typeof app.fetch !== "function") {
+        throw new InferloError("IL5023", "toReactRouterHandlers() needs an Inferlo app (the value returned by createApp).", { fix });
+    }
+    if (options === null || typeof options !== "object" || (options.prefix !== undefined && (typeof options.prefix !== "string" || !options.prefix.startsWith("/")))) {
+        throw new InferloError("IL5023", 'toReactRouterHandlers() prefix must be a path that starts with /, such as "/api".', { fix });
+    }
+    const prefix = normalizePrefix(options.prefix);
+    const handle = async (args) => {
+        const incoming = args?.request;
+        if (!(incoming instanceof Request)) {
+            throw new InferloError("IL5023", "toReactRouterHandlers()'s loader and action were called without a request.", {
+                fix: 'Export them from a resource route module so React Router calls them: export const { loader, action } = toReactRouterHandlers(app, { prefix: "/api" }).',
+            });
+        }
+        const url = new URL(incoming.url);
+        const stripped = prefix ? stripPrefix(url.pathname, prefix) : null;
+        if (stripped === null)
+            return app.fetch(incoming);
+        url.pathname = stripped;
+        const hasBody = incoming.body !== null && incoming.method !== "GET" && incoming.method !== "HEAD";
+        const init = {
+            method: incoming.method,
+            headers: incoming.headers,
+            body: hasBody ? incoming.body : undefined,
+            signal: incoming.signal,
+            redirect: incoming.redirect,
+        };
+        if (hasBody)
+            init.duplex = "half";
+        return app.fetch(new Request(url, init));
+    };
+    return Object.freeze({ loader: handle, action: handle });
+}
+//# sourceMappingURL=react-router.js.map

package/dist/react-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-router.js","sourceRoot":"","sources":["../src/react-router.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA2B1D,MAAM,GAAG,GAAG,sIAAsI,CAAC;AAEnJ;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAA4B,EAAE,UAAsC,EAAE;IAC1G,IAAI,CAAC,GAAG,IAAI,OAAQ,GAA2B,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;QACrE,MAAM,IAAI,YAAY,CAAC,QAAQ,EAAE,iFAAiF,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAC/H,CAAC;IACD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QACjK,MAAM,IAAI,YAAY,CAAC,QAAQ,EAAE,mFAAmF,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACjI,CAAC;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/C,MAAM,MAAM,GAAuB,KAAK,EAAE,IAAI,EAAE,EAAE;QAChD,MAAM,QAAQ,GAAI,IAAwC,EAAE,OAAO,CAAC;QACpE,IAAI,CAAC,CAAC,QAAQ,YAAY,OAAO,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,YAAY,CAAC,QAAQ,EAAE,4EAA4E,EAAE;gBAC7G,GAAG,EAAE,wJAAwJ;aAC9J,CAAC,CAAC;QACL,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAClC,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACnE,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAQ,GAA+B,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC/E,GAAG,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACxB,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,KAAK,IAAI,IAAI,QAAQ,CAAC,MAAM,KAAK,KAAK,IAAI,QAAQ,CAAC,MAAM,KAAK,MAAM,CAAC;QAClG,MAAM,IAAI,GAAsC;YAC9C,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;YACzC,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;SAC5B,CAAC;QACF,IAAI,OAAO;YAAE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAClC,OAAQ,GAA+B,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;IACxE,CAAC,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;AAC3D,CAAC"}

package/dist/redact.d.ts

@@ -0,0 +1,19 @@
+export declare const REDACTED = "[redacted]";
+/** Internal: remember the secret values an object holds (a config() result or an AI provider). */
+export declare function holdSecrets<T extends object>(owner: T, values: readonly (string | undefined | null)[]): T;
+export declare function secretsOf(owner: unknown): readonly string[];
+export interface Redactor {
+    text(value: string): string;
+    value(value: unknown): unknown;
+}
+export declare function createRedactor(secretValues: readonly string[]): Redactor;
+export interface LoggerLike {
+    info(message: string, data?: unknown, fields?: Record<string, string | number | boolean | undefined>): void;
+    error(message: string, data?: unknown, fields?: Record<string, string | number | boolean | undefined>): void;
+}
+/** A logger that redacts every message, data value and field before passing them on. */
+export declare function redactingLogger(logger: LoggerLike, redactor: Redactor): LoggerLike;
+/** The values of createApp({ redact }): strings, or objects that hold secrets (config() results). */
+export declare function redactValues(option: unknown): string[];
+/** Internal: remember a config() result and its secret values, for createApp({ redact: [settings] }). */
+export declare function holdConfigSecrets<T extends object>(settings: T, values: readonly unknown[]): T;

package/dist/redact.js

@@ -0,0 +1,150 @@
+/**
+ * Secret redaction for everything createApp logs (and the error messages exposeErrors shows): credentials in
+ * headers, tokens, API keys, passwords in URLs, the app's AI provider keys and the values passed to
+ * createApp({ redact }). Internal: createApp wraps its logger with redactingLogger().
+ */
+import { InferloError } from "./errors.js";
+export const REDACTED = "[redacted]";
+/** Secret values of objects that hold them (config() results, AI providers), looked up by createApp. */
+const heldSecrets = new WeakMap();
+/** Internal: remember the secret values an object holds (a config() result or an AI provider). */
+export function holdSecrets(owner, values) {
+    const list = values.filter((v) => typeof v === "string" && v.length > 0);
+    if (list.length)
+        heldSecrets.set(owner, [...(heldSecrets.get(owner) ?? []), ...list]);
+    return owner;
+}
+export function secretsOf(owner) {
+    return owner && typeof owner === "object" ? (heldSecrets.get(owner) ?? []) : [];
+}
+const SENSITIVE_KEY = /^(authorization|proxy-authorization|cookie|set-cookie|x-api-key|api[-_]?key|apikey|password|passwd|secret|client[-_]?secret|token|access[-_]?token|refresh[-_]?token|id[-_]?token|private[-_]?key|session)$/i;
+const PATTERNS = [
+    // Header-like "name: value" or "name=value" pairs, also inside JSON text. Cookies run to the end of the value.
+    [/\b(cookie|set-cookie)(["']?\s*[:=]\s*["']?)(?!\[redacted\])[^"'\r\n]+/gi, `$1$2${REDACTED}`],
+    [
+        /\b(authorization|proxy-authorization|x-api-key|api-key)(["']?\s*[:=]\s*["']?)(?:(Bearer|Basic|Token)\s+)?(?!\[redacted\]|(?:Bearer|Basic|Token)\s)[^\s"',;]+/gi,
+        (_match, name, separator, scheme) => `${name}${separator}${scheme ? `${scheme} ` : ""}${REDACTED}`,
+    ],
+    // Bearer <token> and Basic <credentials> anywhere else
+    [/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{4,}/g, `$1 ${REDACTED}`],
+    // Passwords in connection strings and URLs: postgres://user:password@host
+    [/\b([a-z][a-z0-9+.-]*:\/\/[^\s:/@]*:)[^\s@/]+@/gi, `$1${REDACTED}@`],
+    // Secrets in query strings: ?key=..., &access_token=...
+    [/([?&](?:key|api_key|apikey|access_token|token|secret|password|signature|sig)=)[^&\s"'#]+/gi, `$1${REDACTED}`],
+    // Well-known API key formats: OpenAI and Anthropic (sk-...), Google (AIza...), GitHub tokens.
+    [/\bsk-[A-Za-z0-9_-]{16,}/g, REDACTED],
+    [/\bAIza[0-9A-Za-z_-]{30,}/g, REDACTED],
+    [/\bgh[pousr]_[A-Za-z0-9]{30,}/g, REDACTED],
+];
+export function createRedactor(secretValues) {
+    // Longest first, so a secret that contains another is replaced whole. Very short values would hide normal text.
+    const known = [...new Set(secretValues.filter((v) => v.length >= 6))].sort((a, b) => b.length - a.length);
+    const text = (input) => {
+        let out = input;
+        for (const secret of known)
+            if (out.includes(secret))
+                out = out.split(secret).join(REDACTED);
+        for (const [pattern, replacement] of PATTERNS)
+            out = out.replace(pattern, replacement);
+        return out;
+    };
+    const value = (input, depth = 0, seen = new WeakMap()) => {
+        if (typeof input === "string")
+            return text(input);
+        if (!input || typeof input !== "object")
+            return input;
+        if (seen.has(input))
+            return seen.get(input);
+        if (depth > 8)
+            return input;
+        if (input instanceof Error) {
+            const copy = Object.create(Object.getPrototypeOf(input));
+            seen.set(input, copy);
+            Object.defineProperty(copy, "message", { value: text(input.message), writable: true, configurable: true });
+            if (input.stack !== undefined)
+                Object.defineProperty(copy, "stack", { value: text(input.stack), writable: true, configurable: true });
+            if (input.name !== Object.getPrototypeOf(input)?.name)
+                Object.defineProperty(copy, "name", { value: input.name, writable: true, configurable: true });
+            for (const key of Object.keys(input))
+                copy[key] = redactEntry(key, input[key], depth, seen);
+            if ("cause" in input)
+                Object.defineProperty(copy, "cause", { value: value(input.cause, depth + 1, seen), writable: true, configurable: true });
+            return copy;
+        }
+        if (typeof Headers !== "undefined" && input instanceof Headers) {
+            const out = {};
+            seen.set(input, out);
+            input.forEach((v, k) => (out[k] = redactEntry(k, v, depth, seen)));
+            return out;
+        }
+        if (Array.isArray(input)) {
+            const out = [];
+            seen.set(input, out);
+            for (const item of input)
+                out.push(value(item, depth + 1, seen));
+            return out;
+        }
+        const proto = Object.getPrototypeOf(input);
+        if (proto !== Object.prototype && proto !== null)
+            return input;
+        const out = {};
+        seen.set(input, out);
+        for (const [k, v] of Object.entries(input))
+            out[k] = redactEntry(k, v, depth, seen);
+        return out;
+    };
+    const redactEntry = (key, entry, depth, seen) => {
+        if (SENSITIVE_KEY.test(key) && entry !== undefined && entry !== null && entry !== "")
+            return REDACTED;
+        return value(entry, depth + 1, seen);
+    };
+    return { text, value: (input) => value(input) };
+}
+/** A logger that redacts every message, data value and field before passing them on. */
+export function redactingLogger(logger, redactor) {
+    const pass = (level, message, data, fields) => {
+        const text = redactor.text(String(message));
+        if (fields !== undefined) {
+            const clean = {};
+            for (const [key, value] of Object.entries(fields))
+                clean[key] = typeof value === "string" ? redactor.text(value) : value;
+            return logger[level](text, data === undefined ? undefined : redactor.value(data), clean);
+        }
+        return data === undefined ? logger[level](text) : logger[level](text, redactor.value(data));
+    };
+    return {
+        info: (message, data, fields) => pass("info", message, data, fields),
+        error: (message, data, fields) => pass("error", message, data, fields),
+    };
+}
+/** The values of createApp({ redact }): strings, or objects that hold secrets (config() results). */
+export function redactValues(option) {
+    if (option === undefined)
+        return [];
+    if (!Array.isArray(option))
+        throw invalidRedact(`createApp({ redact }) must be an array, got ${typeof option}.`);
+    const out = [];
+    option.forEach((item, i) => {
+        if (item === undefined || item === null || item === "")
+            return; // an unset optional variable
+        if (typeof item === "string")
+            out.push(item);
+        else if (typeof item === "object" && configs.has(item))
+            out.push(...secretsOf(item));
+        else
+            throw invalidRedact(`createApp({ redact }) item ${i} is ${typeof item === "object" ? "an object that is not a config() result" : `a ${typeof item}`}.`);
+    });
+    return out;
+}
+const configs = new WeakSet();
+/** Internal: remember a config() result and its secret values, for createApp({ redact: [settings] }). */
+export function holdConfigSecrets(settings, values) {
+    configs.add(settings);
+    return holdSecrets(settings, values.map((v) => (v === undefined || v === null ? undefined : String(v))));
+}
+function invalidRedact(message) {
+    return new InferloError("IL6018", message, {
+        fix: "Pass the values to hide from logs, or your config() result: createApp({ redact: [settings, process.env.WEBHOOK_SECRET] }).",
+    });
+}
+//# sourceMappingURL=redact.js.map

package/dist/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"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"}

package/dist/request-matcher.d.ts

@@ -0,0 +1,4 @@
+/** Called by createApp with a function that knows the app's routes and built-in endpoints. */
+export declare function registerRequestMatcher(app: object, matcher: (method: string, pathname: string) => boolean): void;
+/** True when the app has a route or built-in endpoint for this method and path; undefined for objects that are not apps from createApp. */
+export declare function appAnswers(app: object, method: string, pathname: string): boolean | undefined;

package/dist/request-matcher.js

@@ -0,0 +1,14 @@
+/**
+ * Which requests an app answers itself, for toNodeHandler(app, { fallthrough: true }). Kept apart from
+ * app.ts so the Node handler (and the framework entry points that use it) load no router code.
+ */
+const matchers = new WeakMap();
+/** Called by createApp with a function that knows the app's routes and built-in endpoints. */
+export function registerRequestMatcher(app, matcher) {
+    matchers.set(app, matcher);
+}
+/** True when the app has a route or built-in endpoint for this method and path; undefined for objects that are not apps from createApp. */
+export function appAnswers(app, method, pathname) {
+    return matchers.get(app)?.(method, pathname);
+}
+//# sourceMappingURL=request-matcher.js.map

package/dist/request-matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-matcher.js","sourceRoot":"","sources":["../src/request-matcher.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAyD,CAAC;AAEtF,8FAA8F;AAC9F,MAAM,UAAU,sBAAsB,CAAC,GAAW,EAAE,OAAsD;IACxG,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AAC7B,CAAC;AAED,2IAA2I;AAC3I,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,MAAc,EAAE,QAAgB;IACtE,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAC/C,CAAC"}

package/dist/route.d.ts

@@ -8,17 +8,21 @@
  *
  * Secure by default: routes require a signed-in user unless you set auth: "public".
  */
+import type { Deprecation } from "./deprecation.ts";
 import type { AI } from "./ai/index.ts";
 import type { Db } from "./db/table.ts";
 import type { Jobs } from "./jobs.ts";
 import type { AnyModel } from "./model.ts";
+import type { Audit } from "./audit.ts";
+import type { Cache, RouteCache } from "./cache.ts";
+import type { PermissionInput, Permissions } from "./permissions.ts";
 import type { RateLimit } from "./rate-limit.ts";
 import type { AnySchema, Infer, ObjectSchema } from "./schema.ts";
 /**
  * Register your app's models and user type once, so every handler is fully typed:
  *
  *   declare module "@browserlessapi/inferlo" {
- *     interface Register { models: typeof models; user: User }
+ *     interface Register { models: typeof models; user: User; permissions: typeof access }
  *   }
  */
 export interface Register {
@@ -32,6 +36,15 @@ export type AppUser = Registered<"user", {
     roles?: string[];
 }>;
 export type AppDb = Db<AppModels>;
+/**
+ * The permission names a route's `permission` option accepts. With `permissions: typeof access` in Register, only the
+ * names whose rule needs nothing but { user } (roles rules and rules of the user alone), so a typo is a type error.
+ */
+export type AppPermission = Registered<"permissions", undefined> extends Permissions<infer R> ? {
+    [K in keyof R & string]: {
+        user: AppUser;
+    } extends PermissionInput<R[K]> ? K : never;
+}[keyof R & string] : string;
 export type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 /** "public": anyone. "user": any signed-in user. Any other string: the user must have that role. */
 export type Auth = "public" | "user" | (string & {});
@@ -44,6 +57,12 @@ export interface ToolOptions {
 export interface RouteOptions<B extends AnySchema | undefined, Q extends ObjectSchema<any> | undefined, P extends ObjectSchema<any> | undefined> {
     /** Who may call this route. Default "user" (signed in). */
     auth?: Auth;
+    /**
+     * A permission from createApp({ permissions }) the signed-in user must have, checked with { user } before the
+     * handler runs (also when the route is called as an AI tool). Denied: 403 IL3004. For rules that also need a
+     * resource, call access.authorize(name, { user, ticket }) in the handler instead. Typed from Register's permissions.
+     */
+    permission?: AppPermission;
     /** Request body schema (JSON or form). */
     body?: B;
     /** Query string schema. Strings are converted to numbers and booleans automatically. */
@@ -60,6 +79,22 @@ export interface RouteOptions<B extends AnySchema | undefined, Q extends ObjectS
     tool?: boolean | ToolOptions;
     /** Limit requests per user or IP: { max: 10, per: "minute", by: "user" }. More raise IL2005 (HTTP 429). */
     rateLimit?: RateLimit;
+    /**
+     * Longest time in milliseconds this route may take (reading the body and running the handler) before it
+     * answers 503 IL2007 and ctx.signal is aborted. Overrides createApp({ requestTimeoutMs }); false turns it off.
+     */
+    timeoutMs?: number | false;
+    /**
+     * Mark the route deprecated: true, or { since, sunset, link } to also send the Deprecation, Sunset and
+     * Link rel="deprecation" headers on every response. Shown in OpenAPI, describe and MCP tool descriptions.
+     */
+    deprecated?: boolean | Deprecation;
+    /**
+     * Cache this GET route's JSON responses in the app cache: { ttlMs: 60_000, by: "user", tags: ["tickets"] }.
+     * "user" (default) keeps one response per signed-in user, "public" one for every caller. Remove them early with
+     * ctx.cache.invalidate(tag). Responses carry an ETag, so clients revalidate with If-None-Match (304).
+     */
+    cache?: RouteCache;
 }
 type PathParams<P extends string> = P extends `${string}:${infer Param}/${infer Rest}` ? {
     [K in Param | keyof PathParams<`/${Rest}`>]: string;
@@ -77,6 +112,8 @@ export interface Context<Body, Query, Params, User> {
     ai: AI;
     /** Queue background jobs: await jobs.enqueue(sendEmail, { to }). */
     jobs: Jobs;
+    /** The app cache: await cache.getOrSet(key, { ttlMs: 60_000, tags: ["tickets"] }, compute), cache.invalidate("tickets"). */
+    cache: Cache;
     req: Request;
     url: URL;
     headers: Headers;
@@ -86,8 +123,20 @@ export interface Context<Body, Query, Params, User> {
     header(name: string, value: string): void;
     /** Values shared by middleware for this request. */
     state: Record<string, unknown>;
+    /**
+     * Aborted when the request times out (requestTimeoutMs or the route's timeoutMs) or the client disconnects.
+     * ctx.ai calls use it automatically; pass it to fetch and other slow work: fetch(url, { signal }).
+     */
+    signal: AbortSignal;
+    /** This request's id: sent back in the X-Request-Id header and added to the request's log entries. */
+    requestId: string;
     /** Run work after the response is sent (logging, webhooks). Errors are logged, not thrown. */
     waitUntil(promise: Promise<unknown>): void;
+    /**
+     * Write an audit log entry with the signed-in user and this request's id (needs AuditLog in createApp({ models })):
+     * await audit("tickets.update", { model: "tickets", before: ticket, after: updated }).
+     */
+    audit: Audit;
 }
 export type AnyContext = Context<any, any, any, any>;
 export type Handler<C, R> = (ctx: C) => R | Promise<R>;
@@ -99,6 +148,8 @@ export interface RouteDef {
     readonly handler: Handler<AnyContext, unknown>;
     /** Export name, filled in by createApp when routes are passed as modules. */
     name?: string;
+    /** API version ("v1") when the route comes from apiVersion("v1", routes). */
+    readonly version?: string;
 }
 export declare class RouteBuilder<Path extends string, B extends AnySchema | undefined, Q extends ObjectSchema<any> | undefined, P extends ObjectSchema<any> | undefined, A> {
     readonly method: Method;
@@ -128,4 +179,6 @@ export declare const route: {
     }) => RouteBuilder<Path, B, Q, P, A>;
 };
 export declare function isRoute(value: unknown): value is RouteDef;
+/** The routes in route sources: routes, arrays and modules (import * as tickets), named after their exports. */
+export declare function collectRoutes(sources: unknown): RouteDef[];
 export {};