@renoxium/sdk 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export type { Authz, AuthzContext, AuthzRoles, CloseContext, ConfigValue, Conn, Ctx, Deadline, Decision, EnqueueOptions, Explanation, Guard, JobContext, JobInfo, JobModule, JobPage, Ai, AiContent, AiMessage, AiRequest, AiResult, AiTool, Pdf, PdfOptions, Storage, StoragePage, StoragePutOptions, StoredFile, Webhook, WebhookContext, WebhookEvent, WebhookProvider, JobRow, JobState, Jobs, MessageContext, Principal, PrincipalRole, Realtime, RealtimeContext, RealtimePayload, ResourceRef, RoleAssignment, RoleScope, SseModule, Tool, ToolContext, ToolDefinition, ToolInputSchema, WsModule, DeliveredEvent, EmitOptions, EventContext, EventHandler, EventInfo, Events, Fetch, FunctionModule, Handler, HookFiller, HookFillerResult, HookRunResult, Hooks, HooksModule, HttpMethod, JsonValue, Log, LogFields, LogLevel, ModuleConfig, ModuleServices, Params, Password, Secrets, ServiceFunction, ServiceImplementation, Services, ServicesModule, } from "./ctx.ts";
+export { defineHandlers } from "./ctx.ts";
+export type { ActionName, ScopedDb } from "./authz.ts";
+export { defineGuard, isForbidden, resource, userScope } from "./authz.ts";
+export { defineSse, defineWs, isTopic, MAX_TOPIC_LENGTH, topic } from "./realtime.ts";
+export { INPUT_KEYWORDS, tool, toolInputSchema } from "./tools.ts";
+export { defineJob, isTimeZone, parseSchedule } from "./jobs.ts";
+export type { TotpAlgorithm, TotpOptions, VerifyOptions } from "./totp.ts";
+export { base32Decode, base32Encode, generateTotpSecret, totp, totpUri, verifyTotp } from "./totp.ts";
+export type { Binary, RegisteredCredential } from "./webauthn.ts";
+export { base64url, COSE_ES256, COSE_RS256, decodeCbor, fromBase64url, verifyAssertion, verifyRegistration, WebAuthnError, webauthnChallenge } from "./webauthn.ts";
+export type { Action, ActionContext, ActionResult, Loader, LoaderContext, PageData, PageModule, Session, TextDirection } from "./pages.ts";
+export { definePage } from "./pages.ts";
+export type { EventHandlerOf, HookFillerOf, HooksDefinition, ModuleCtx, ModuleMap, ModuleSpec, ServiceDefinitions, ServiceProxy, ServicesOf, TypedEvents, TypedHooks, } from "./modules.ts";
+export { defineHooks, defineServices, on } from "./modules.ts";
+export type { StandardSchemaV1, ValidateInput, ValidationIssue } from "./validate.ts";
+export { formToObject, validate, ValidationError } from "./validate.ts";
+export { timingSafeEqual } from "./crypto.ts";
+export type { RedirectStatus, SafeRedirectOptions } from "./redirect.ts";
+export { redirect, safeRedirectTarget } from "./redirect.ts";
+export type { Db, DbStatements, ExecuteResult, Param, Row, Scope, Value } from "./db.ts";
+export type { AuthzErrorCode, DbErrorCode, DbScopeReason, DbUsageErrorCode, ForbiddenErrorDetails, ForbiddenReason, RealtimeErrorCode, JobErrorCode, StorageErrorCode, AiErrorCode, JobOp, RealtimeLimitReason, ToolErrorCode, ErrorResponseBody, FetchBlockedReason, FetchErrorCode, FetchFailedReason, EventPayloadReason, ModuleErrorCode, ModuleServiceErrorDetails, RenoxErrorCode, ResponseErrorCode, } from "./errors.ts";
+export { DbBusyError, DbConstraintError, DbPermissionError, DbQuotaError, DbScopeError, DbSqlError, DbTimeoutError, DbUsageError, DeadlineError, EventPayloadError, FetchBlockedError, FetchEgressLimitError, FetchError, ForbiddenError, JobNotFoundError, JobStateError, AiQuotaError, AiUnavailableError, PdfLimitError, StorageError, isRenoxError, ModuleServiceError, ModuleUndeclaredError, RealtimeBackpressureError, RealtimeLimitError, RENOX_ERROR_CODES, RenoxError, RESPONSE_ERROR_CODES, } from "./errors.ts";

package/dist/index.js

@@ -0,0 +1,15 @@
+// The `@renoxium/sdk` package: types and helpers for tenant code.
+// Contract: docs/contracts/ops.md (version 1.6.0) and docs/contracts/ctx.d.ts.
+export { defineHandlers } from "./ctx.js";
+export { defineGuard, isForbidden, resource, userScope } from "./authz.js";
+export { defineSse, defineWs, isTopic, MAX_TOPIC_LENGTH, topic } from "./realtime.js";
+export { INPUT_KEYWORDS, tool, toolInputSchema } from "./tools.js";
+export { defineJob, isTimeZone, parseSchedule } from "./jobs.js";
+export { base32Decode, base32Encode, generateTotpSecret, totp, totpUri, verifyTotp } from "./totp.js";
+export { base64url, COSE_ES256, COSE_RS256, decodeCbor, fromBase64url, verifyAssertion, verifyRegistration, WebAuthnError, webauthnChallenge } from "./webauthn.js";
+export { definePage } from "./pages.js";
+export { defineHooks, defineServices, on } from "./modules.js";
+export { formToObject, validate, ValidationError } from "./validate.js";
+export { timingSafeEqual } from "./crypto.js";
+export { redirect, safeRedirectTarget } from "./redirect.js";
+export { DbBusyError, DbConstraintError, DbPermissionError, DbQuotaError, DbScopeError, DbSqlError, DbTimeoutError, DbUsageError, DeadlineError, EventPayloadError, FetchBlockedError, FetchEgressLimitError, FetchError, ForbiddenError, JobNotFoundError, JobStateError, AiQuotaError, AiUnavailableError, PdfLimitError, StorageError, isRenoxError, ModuleServiceError, ModuleUndeclaredError, RealtimeBackpressureError, RealtimeLimitError, RENOX_ERROR_CODES, RenoxError, RESPONSE_ERROR_CODES, } from "./errors.js";

package/dist/jobs.d.ts

@@ -0,0 +1,16 @@
+import type { JobModule } from "./ctx.ts";
+/** The values of each field of a schedule (`0 3 * * 1-5`), or the first problem as a string. */
+export declare function parseSchedule(expr: string): number[][] | string;
+/** Whether `tz` is an IANA zone the runtime knows (`Asia/Dubai`, `UTC`). */
+export declare function isTimeZone(tz: string): boolean;
+/**
+ * Checks a job declaration and returns it unchanged; spread it into the
+ * module's exports or use its fields:
+ *
+ * ```ts
+ * export const schedule = "0 3 * * *";
+ * export const tz = "Asia/Dubai";
+ * export async function run(ctx: JobContext) { ... }
+ * ```
+ */
+export declare function defineJob<const J extends JobModule>(job: J): J;

package/dist/jobs.js

@@ -0,0 +1,72 @@
+// Scheduled jobs (#284; docs/contracts/ops.md section 20; run by the F6
+// scheduler, #297). A `jobs/*.ts` module exports `schedule` (five cron
+// fields), optionally `tz`, and `run(ctx)`. `renox build` reads `schedule`
+// and `tz` into the `job` route entry and checks them (V27) with
+// `parseSchedule` below.
+/** One field: allowed range and name. */
+const FIELDS = [
+    { name: "minute", min: 0, max: 59 },
+    { name: "hour", min: 0, max: 23 },
+    { name: "day-of-month", min: 1, max: 31 },
+    { name: "month", min: 1, max: 12 },
+    { name: "day-of-week", min: 0, max: 7 },
+];
+/** The values of each field of a schedule (`0 3 * * 1-5`), or the first problem as a string. */
+export function parseSchedule(expr) {
+    if (typeof expr !== "string" || expr.length > 128)
+        return "a schedule is a string of at most 128 characters";
+    const parts = expr.trim().split(/\s+/u);
+    if (parts.length !== 5)
+        return `a schedule has 5 fields (minute hour day-of-month month day-of-week), got ${parts.length}`;
+    const out = [];
+    for (let f = 0; f < 5; f++) {
+        const { name, min, max } = FIELDS[f];
+        const values = new Set();
+        for (const item of parts[f].split(",")) {
+            const m = /^(\*|(\d+)(?:-(\d+))?)(?:\/(\d+))?$/u.exec(item);
+            if (!m)
+                return `${name}: ${JSON.stringify(item)} is not a number, *, a range a-b, or a step /n`;
+            const from = m[1] === "*" ? min : Number(m[2]);
+            const to = m[1] === "*" ? max : m[3] !== undefined ? Number(m[3]) : m[4] !== undefined ? max : from;
+            const step = m[4] !== undefined ? Number(m[4]) : 1;
+            if (from < min || to > max || from > to)
+                return `${name}: ${item} is outside ${min}-${max}`;
+            if (step < 1)
+                return `${name}: the step of ${item} must be at least 1`;
+            for (let v = from; v <= to; v += step)
+                values.add(v);
+        }
+        out.push([...values].sort((a, b) => a - b));
+    }
+    return out;
+}
+/** Whether `tz` is an IANA zone the runtime knows (`Asia/Dubai`, `UTC`). */
+export function isTimeZone(tz) {
+    try {
+        new Intl.DateTimeFormat("en", { timeZone: tz });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Checks a job declaration and returns it unchanged; spread it into the
+ * module's exports or use its fields:
+ *
+ * ```ts
+ * export const schedule = "0 3 * * *";
+ * export const tz = "Asia/Dubai";
+ * export async function run(ctx: JobContext) { ... }
+ * ```
+ */
+export function defineJob(job) {
+    const parsed = parseSchedule(job.schedule);
+    if (typeof parsed === "string")
+        throw new TypeError(`defineJob: ${parsed}`);
+    if (job.tz !== undefined && !isTimeZone(job.tz))
+        throw new TypeError(`defineJob: ${job.tz} is not an IANA time zone`);
+    if (typeof job.run !== "function")
+        throw new TypeError("defineJob: run must be a function");
+    return job;
+}

package/dist/kysely.d.ts

@@ -0,0 +1,11 @@
+import { type Dialect, Kysely } from "kysely";
+import type { Db, DbStatements } from "./db.ts";
+/** The SQLite dialect over the `db` op. */
+export declare function renoxDialect(db: Db | DbStatements): Dialect;
+/**
+ * A Kysely instance over `ctx.db` (or over the `tx` of `db.transaction`, or
+ * an action's `ctx.db`). `DB` is the `Tables` type of `.renox/types/db.d.ts`.
+ */
+export declare function kysely<DB>(ctx: {
+    readonly db: Db | DbStatements;
+}): Kysely<DB>;

package/dist/kysely.js

@@ -0,0 +1,126 @@
+// `@renoxium/sdk/kysely`: Kysely over the `db` op (docs/06-data.md, "API layers";
+// #237). A thin driver: every compiled query goes to `ctx.db.query` or
+// `execute` with its `?` parameters in order, so the platform's limits and
+// the module authorizer apply exactly as to raw SQL; there is no second
+// execution path. Transactions run through `db.transaction` (a savepoint
+// when one is already current, ops.md section 1). No streaming.
+//
+//   import { kysely } from "@renoxium/sdk/kysely";
+//   import type { Tables } from "../.renox/types/db";
+//   const rows = await kysely<Tables>(ctx).selectFrom("app__products").selectAll().where("id", "=", id).execute();
+//
+// `kysely` is an optional peer dependency: an app that never imports this
+// subpath does not need it.
+import { Kysely, SqliteAdapter, SqliteIntrospector, SqliteQueryCompiler, } from "kysely";
+/** A statement writes and returns no rows unless it is a SELECT, a WITH ... SELECT, or carries RETURNING. */
+function returnsRows(query) {
+    const kind = query.query.kind;
+    if (kind === "SelectQueryNode")
+        return true;
+    return /\breturning\b/iu.test(query.sql) || /^\s*(select|with|pragma|values)\b/iu.test(query.sql);
+}
+function params(query) {
+    return query.parameters.map((p) => (p instanceof Date ? p.toISOString() : p));
+}
+class RenoxConnection {
+    db;
+    /** The open transaction while Kysely runs one on this connection. */
+    tx;
+    constructor(db) {
+        this.db = db;
+    }
+    async executeQuery(query) {
+        if (returnsRows(query)) {
+            const rows = await this.db.query(query.sql, params(query));
+            return { rows: rows };
+        }
+        const r = await this.db.execute(query.sql, params(query));
+        return { rows: [], numAffectedRows: BigInt(r.changes), insertId: BigInt(r.lastInsertRowid) };
+    }
+    async *streamQuery() {
+        throw new Error("@renoxium/sdk/kysely: streaming queries are not supported; use execute()");
+    }
+}
+/**
+ * Kysely's begin/commit/rollback over the callback form of `db.transaction`:
+ * `begin` opens the transaction and parks its callback until `commit`
+ * resolves it or `rollback` rejects it.
+ */
+class TransactionConnection extends RenoxConnection {
+    finish;
+    done;
+    static async open(db) {
+        let ready;
+        const opened = new Promise((r) => (ready = r));
+        const done = db.transaction((tx) => new Promise((resolve, reject) => {
+            const conn = new TransactionConnection(tx);
+            conn.finish = (commit) => (commit ? resolve() : reject(new RollbackSignal()));
+            ready(conn);
+        }));
+        const conn = await Promise.race([opened, done.then(() => Promise.reject(new Error("transaction ended before it began")))]);
+        conn.done = done.catch((e) => {
+            if (!(e instanceof RollbackSignal))
+                throw e;
+        });
+        return conn;
+    }
+    async end(commit) {
+        this.finish(commit);
+        await this.done;
+    }
+}
+class RollbackSignal extends Error {
+}
+class RenoxDriver {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async init() { }
+    async acquireConnection() {
+        return new RenoxConnection(this.db);
+    }
+    async beginTransaction(connection) {
+        if (!("transaction" in this.db))
+            throw new Error("@renoxium/sdk/kysely: this db is already a transaction; run the queries on it directly");
+        // Kysely runs the transaction's queries on the connection it passes to
+        // `beginTransaction`: from here on that connection forwards to the
+        // transaction.
+        const c = connection;
+        c.tx = await TransactionConnection.open(this.db);
+        c.db = c.tx.db;
+    }
+    async commitTransaction(connection) {
+        await this.endTx(connection, true);
+    }
+    async rollbackTransaction(connection) {
+        await this.endTx(connection, false);
+    }
+    async endTx(connection, commit) {
+        const c = connection;
+        const tx = c.tx;
+        if (tx === undefined)
+            throw new Error("@renoxium/sdk/kysely: no open transaction");
+        c.tx = undefined;
+        c.db = this.db;
+        await tx.end(commit);
+    }
+    async releaseConnection() { }
+    async destroy() { }
+}
+/** The SQLite dialect over the `db` op. */
+export function renoxDialect(db) {
+    return {
+        createAdapter: () => new SqliteAdapter(),
+        createDriver: () => new RenoxDriver(db),
+        createIntrospector: (k) => new SqliteIntrospector(k),
+        createQueryCompiler: () => new SqliteQueryCompiler(),
+    };
+}
+/**
+ * A Kysely instance over `ctx.db` (or over the `tx` of `db.transaction`, or
+ * an action's `ctx.db`). `DB` is the `Tables` type of `.renox/types/db.d.ts`.
+ */
+export function kysely(ctx) {
+    return new Kysely({ dialect: renoxDialect(ctx.db) });
+}

package/dist/modules.d.ts

@@ -0,0 +1,72 @@
+import type { ConfigValue, Ctx, DeliveredEvent, EmitOptions, EventContext, HookFiller, HookFillerResult, HookRunResult } from "./ctx.ts";
+/** What the generated types say about one module. */
+export interface ModuleSpec {
+    /** Caller-side services (the broker supplies the callee's ctx). */
+    services: object;
+    /** Event name → payload type, for the events the module exports. */
+    events: object;
+    /** Hook name → `{ args, result }`, for the hook points the module exports. */
+    hooks: object;
+    /** Config key → value type. */
+    config: object;
+}
+/** Installed module name → its spec; `app` has no events, hooks, or config. */
+export type ModuleMap = Record<string, ModuleSpec>;
+/**
+ * A `services.ts` export as a caller sees it: the leading `ctx` parameter is
+ * dropped and the result is a promise (ops.md section 15.2).
+ */
+export type ServiceProxy<F> = F extends (ctx: never, ...args: infer A) => infer R ? (...args: A) => Promise<Awaited<R>> : never;
+/** All the services of a `services.ts` module, as proxies. */
+export type ServicesOf<T> = {
+    readonly [K in keyof T as T[K] extends (...args: never[]) => unknown ? K : never]: ServiceProxy<T[K]>;
+};
+/** `ctx.events` with the module's own event names and payloads. */
+export interface TypedEvents<E> {
+    emit<N extends keyof E & string>(name: N, payload: E[N], options?: EmitOptions): Promise<string>;
+}
+/** `ctx.hooks` with the module's own hook points. */
+export interface TypedHooks<H> {
+    run<N extends keyof H & string>(name: N, args: H[N] extends {
+        args: infer A;
+    } ? A : unknown): Promise<HookRunResult>;
+}
+/**
+ * The ctx of module `M`: the contract's `Ctx` with `services` typed for every
+ * installed module, `events` and `hooks` for `M`'s own exports, and `config`
+ * for `M`'s `[config]`.
+ */
+export type ModuleCtx<Ms extends ModuleMap, M extends keyof Ms | "app"> = Omit<Ctx, "services" | "events" | "hooks" | "config"> & {
+    readonly services: {
+        readonly [K in keyof Ms]: Ms[K]["services"];
+    };
+    readonly events: TypedEvents<M extends keyof Ms ? Ms[M]["events"] : Record<never, never>>;
+    readonly hooks: TypedHooks<M extends keyof Ms ? Ms[M]["hooks"] : Record<never, never>>;
+    readonly config: Readonly<M extends keyof Ms ? Ms[M]["config"] : Record<string, ConfigValue>>;
+};
+/** The shape `services.ts` exports: each service takes the callee's ctx first. */
+export type ServiceDefinitions = Record<string, (ctx: never, ...args: never[]) => unknown>;
+/**
+ * Types a `services.ts` module's exports in one place and returns them
+ * unchanged: `export const { getActivePlan } = defineServices({ ... })`.
+ */
+export declare function defineServices<const S extends ServiceDefinitions>(services: S): S;
+/** One hook filler, typed by its args. */
+export interface HookFillerOf<A> {
+    readonly priority?: number;
+    handle(ctx: Ctx, args: A): HookFillerResult | Promise<HookFillerResult>;
+}
+/** One event handler, typed by its payload. */
+export type EventHandlerOf<P> = (ctx: EventContext, e: DeliveredEvent<P>) => void | Promise<void>;
+/** What `hooks.ts` exports: `{ hooks, on }` (ops.md sections 15.3 and 15.4). */
+export interface HooksDefinition {
+    hooks?: Readonly<Record<string, HookFiller | HookFillerOf<never>>>;
+    on?: Readonly<Record<string, EventHandlerOf<never>>>;
+}
+/**
+ * Types a `hooks.ts` module in one place and returns it unchanged:
+ * `export const { hooks, on } = defineHooks({ hooks: { ... }, on: { ... } })`.
+ */
+export declare function defineHooks<const H extends HooksDefinition>(definition: H): H;
+/** A typed event handler for the `on` map: `on: { "billing.invoice_paid": on<Paid>(async (ctx, e) => ...) }`. */
+export declare function on<P>(handler: EventHandlerOf<P>): EventHandlerOf<P>;

package/dist/modules.js

@@ -0,0 +1,30 @@
+// Typed module APIs (docs/contracts/ops.md section 15; docs/10-modules.md).
+// `Ctx.services`, `events`, `hooks` and `config` are untyped in the
+// contract; the CLI generates `.renox/types/modules.d.ts` from the installed
+// manifests (#236), and `ModuleCtx` narrows the contract's `Ctx` with it.
+//
+//   import type { ModuleCtx } from "../.renox/types/modules";
+//   export const services = defineServices({
+//     async getActivePlan(ctx: ModuleCtx<"billing">, userId: string) {
+//       const user = await ctx.services.auth.currentUser();   // typed from auth's services.ts
+//       await ctx.events.emit("billing.invoice_paid", { invoice_id: "i1", user_id: userId }); // payload checked
+//     },
+//   });
+/**
+ * Types a `services.ts` module's exports in one place and returns them
+ * unchanged: `export const { getActivePlan } = defineServices({ ... })`.
+ */
+export function defineServices(services) {
+    return services;
+}
+/**
+ * Types a `hooks.ts` module in one place and returns it unchanged:
+ * `export const { hooks, on } = defineHooks({ hooks: { ... }, on: { ... } })`.
+ */
+export function defineHooks(definition) {
+    return definition;
+}
+/** A typed event handler for the `on` map: `on: { "billing.invoice_paid": on<Paid>(async (ctx, e) => ...) }`. */
+export function on(handler) {
+    return handler;
+}

package/dist/pages.d.ts

@@ -0,0 +1,53 @@
+import type { Ctx } from "./ctx.ts";
+import type { DbStatements } from "./db.ts";
+/** The session of the request; F2 carries only the id (ops.md section 14, "Session"). */
+export interface Session {
+    /** Opaque random id, 22 base64url characters, from the signed `__Host-renox_sid` cookie. */
+    readonly id: string;
+}
+export type TextDirection = "ltr" | "rtl";
+export interface LoaderContext extends Ctx {
+    /** The fragment the cell will render for this request, or null for the full page. */
+    readonly fragment: string | null;
+    readonly session: Session;
+    /** Sets the page's locale and direction (ops.md section 14, "Locale"); `dir` defaults from the language. */
+    setLocale(locale: string, dir?: TextDirection): void;
+}
+/** The template data a loader returns: a plain object (ops.md section 14, "Loader"). */
+export type PageData = Record<string, unknown>;
+export type Loader = (ctx: LoaderContext) => PageData | Response | Promise<PageData | Response>;
+export interface ActionContext extends Omit<Ctx, "db"> {
+    /** The action's own IMMEDIATE transaction: committed when the action resolves, rolled back when it throws. */
+    readonly db: DbStatements;
+    /** The action name from `?/<name>`, or "default". */
+    readonly action: string;
+    /** The parsed form body (urlencoded or multipart); empty for other content types. CSRF is checked before. */
+    readonly form: FormData;
+    readonly fragment: string | null;
+    readonly session: Session;
+    /** As for the loader. */
+    setLocale(locale: string, dir?: TextDirection): void;
+}
+/**
+ * A `Response` is sent as is. An object (or nothing) re-runs `load` and is
+ * merged over its result as template data; `fragments` names the extra
+ * fragments rendered out of band.
+ */
+export type ActionResult = Response | (PageData & {
+    fragments?: readonly string[];
+}) | void;
+export type Action = (ctx: ActionContext) => ActionResult | Promise<ActionResult>;
+/** Shape of a `pages/**\/*.ts` module. */
+export interface PageModule {
+    load?: Loader;
+    actions?: Readonly<Record<string, Action>>;
+}
+/**
+ * Optional sugar: types a page's `load` and `actions` in one place and
+ * returns them unchanged.
+ *
+ * ```ts
+ * export const { load, actions } = definePage({ load: async ({ db }) => ({ ... }), actions: { add: async ({ form }) => ... } });
+ * ```
+ */
+export declare function definePage<const P extends PageModule>(page: P): P;

package/dist/pages.js

@@ -0,0 +1,14 @@
+// Page modules (docs/contracts/ops.md section 14): `pages/**/*.ts` export
+// `load` and `actions`. Types identical to docs/contracts/ctx.d.ts;
+// tests/contract.test-d.ts enforces it.
+/**
+ * Optional sugar: types a page's `load` and `actions` in one place and
+ * returns them unchanged.
+ *
+ * ```ts
+ * export const { load, actions } = definePage({ load: async ({ db }) => ({ ... }), actions: { add: async ({ form }) => ... } });
+ * ```
+ */
+export function definePage(page) {
+    return page;
+}

package/dist/realtime.d.ts

@@ -0,0 +1,15 @@
+import type { SseModule, WsModule } from "./ctx.ts";
+/** Topics are at most 256 characters. */
+export declare const MAX_TOPIC_LENGTH = 256;
+/** Whether `t` is a topic the platform accepts (`room:42`, `user:u_1:inbox`). */
+export declare function isTopic(t: string): boolean;
+/**
+ * A topic from its segments, joined with `:`. Throws a RangeError for a
+ * segment outside `[A-Za-z0-9_.-]+` (a `:` inside a segment would change
+ * the topic) or a topic over 256 characters, as `ctx.realtime` does.
+ */
+export declare function topic(...segments: readonly (string | number)[]): string;
+/** Types a `functions/ws/**` module's `ws` export and returns it unchanged. */
+export declare function defineWs<const M extends WsModule>(handlers: M): M;
+/** Types a `functions/sse/**` module's `sse` export and returns it unchanged. */
+export declare function defineSse<const M extends SseModule>(handlers: M): M;

package/dist/realtime.js

@@ -0,0 +1,40 @@
+// Realtime helpers (#284; docs/contracts/ops.md section 18). The handler
+// shapes (`WsModule`, `SseModule`) and `ctx.realtime` are in ctx.ts; these
+// type a module's export and build topics the way the platform checks them.
+//
+//   // functions/ws/chat/[room].ts
+//   export const ws = defineWs({
+//     async open(ctx) { await ctx.realtime.subscribe(ctx.conn, topic("room", ctx.params.room as string)); },
+//     async message(ctx) { await ctx.realtime.publish(topic("room", ctx.params.room as string), { text: String(ctx.data) }); },
+//   });
+/** One topic segment: `[A-Za-z0-9_.-]+` (ops.md section 18, "Topics"). */
+const SEGMENT = /^[A-Za-z0-9_.-]+$/u;
+/** Topics are at most 256 characters. */
+export const MAX_TOPIC_LENGTH = 256;
+/** Whether `t` is a topic the platform accepts (`room:42`, `user:u_1:inbox`). */
+export function isTopic(t) {
+    return typeof t === "string" && t.length > 0 && t.length <= MAX_TOPIC_LENGTH && t.split(":").every((s) => SEGMENT.test(s));
+}
+/**
+ * A topic from its segments, joined with `:`. Throws a RangeError for a
+ * segment outside `[A-Za-z0-9_.-]+` (a `:` inside a segment would change
+ * the topic) or a topic over 256 characters, as `ctx.realtime` does.
+ */
+export function topic(...segments) {
+    const parts = segments.map(String);
+    for (const p of parts)
+        if (!SEGMENT.test(p))
+            throw new RangeError(`topic: segment ${JSON.stringify(p)} is not [A-Za-z0-9_.-]+`);
+    const t = parts.join(":");
+    if (t.length === 0 || t.length > MAX_TOPIC_LENGTH)
+        throw new RangeError("topic: 1 to 256 characters");
+    return t;
+}
+/** Types a `functions/ws/**` module's `ws` export and returns it unchanged. */
+export function defineWs(handlers) {
+    return handlers;
+}
+/** Types a `functions/sse/**` module's `sse` export and returns it unchanged. */
+export function defineSse(handlers) {
+    return handlers;
+}

package/dist/redirect.d.ts

@@ -0,0 +1,19 @@
+export type RedirectStatus = 301 | 302 | 303 | 307 | 308;
+export interface SafeRedirectOptions {
+    /** Origins other than the app's own that may be redirected to, e.g. `"https://accounts.example.com"`. */
+    readonly allow?: readonly string[];
+    /** Where an unsafe target goes instead: a path of the app (default `"/"`). */
+    readonly fallback?: string;
+    /** Default 303 (See Other): the right answer to a form `POST`. */
+    readonly status?: RedirectStatus;
+}
+/**
+ * The `Location` to send for `target`, or `null` when it is not safe: a
+ * path of this app (`/…`, not `//…`, no `\`, no control characters), or an
+ * absolute `http(s)` URL whose origin is in `allow`.
+ */
+export declare function safeRedirectTarget(target: string, allow?: readonly string[]): string | null;
+export declare const redirect: {
+    /** A redirect `Response` to `target` if it is safe (see {@link safeRedirectTarget}), else to `fallback`. */
+    safe(target: string, options?: SafeRedirectOptions): Response;
+};

package/dist/redirect.js

@@ -0,0 +1,57 @@
+// Open-redirect protection (docs/24-threat-model.md, "Open redirect via
+// `next`/`return_to`"; #111). `redirect.safe(target)` redirects only to a
+// path of the app itself or to an origin listed in `allow`; anything else
+// (another site, `//evil.example`, `/\evil.example`, `javascript:`, a
+// relative path without a leading `/`) redirects to `fallback` instead.
+// `renox check` reports `Response.redirect()` with a target taken from the
+// request (`no-unsafe-redirect`).
+// Browsers drop tabs and newlines inside URLs and treat `\` as `/`, so
+// "/\tevil.example" and "/\\evil.example" are protocol-relative to them.
+const CONTROL = /[\u0000-\u001f\u007f]/u;
+function origins(allow) {
+    const out = new Set();
+    for (const a of allow) {
+        try {
+            const u = new URL(a);
+            if (u.protocol === "https:" || u.protocol === "http:")
+                out.add(u.origin);
+        }
+        catch {
+            // An entry that is not an absolute URL allows nothing.
+        }
+    }
+    return out;
+}
+/**
+ * The `Location` to send for `target`, or `null` when it is not safe: a
+ * path of this app (`/…`, not `//…`, no `\`, no control characters), or an
+ * absolute `http(s)` URL whose origin is in `allow`.
+ */
+export function safeRedirectTarget(target, allow = []) {
+    if (typeof target !== "string" || target.length === 0 || target.length > 2048)
+        return null;
+    if (CONTROL.test(target) || target.includes("\\"))
+        return null;
+    if (target.startsWith("/"))
+        return target.startsWith("//") ? null : target;
+    let url;
+    try {
+        url = new URL(target);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        return null;
+    if (url.username || url.password)
+        return null;
+    return origins(allow).has(url.origin) ? url.href : null;
+}
+export const redirect = {
+    /** A redirect `Response` to `target` if it is safe (see {@link safeRedirectTarget}), else to `fallback`. */
+    safe(target, options = {}) {
+        const fallback = safeRedirectTarget(options.fallback ?? "/") ?? "/";
+        const location = safeRedirectTarget(target, options.allow ?? []) ?? fallback;
+        return new Response(null, { status: options.status ?? 303, headers: { location } });
+    },
+};