@trylight/app 0.1.0 → 0.1.1

package/README.md

@@ -7,9 +7,9 @@ unchanged; entities and the schema sync are new here.
 
 | Import | What |
 |---|---|
-| `@trylight/app/schema` | `entity(name, columns, access)`: a Drizzle table plus `id`, `created_at`, `updated_at`, `created_by`, `field_sources`; `lightChanges` (the audit table); `fieldSource` (the `{url, evidence}` schema) |
-| `@trylight/app` | `createApp<typeof contracts>()` → `app.table(entity)` (`list/get/create/update/delete`, `useList/useGet/useCreate/useUpdate/useDelete`, typed by the entity passed) and `app.contracts` (`useInvocation`) |
-| `@trylight/app/server` | `createLightServer({ schema, contracts })` → `light.db` (Drizzle), `light.session(request)`, `light.signIn(email, password)`, and the route handlers `light.entities`, `light.invoke.handler`, `light.chat` |
+| `@trylight/app/schema` | `entity(name, columns, access)`: a Drizzle table plus `id`, `created_at`, `updated_at`, `created_by`, `field_sources`; `lightChanges` (the audit table); `lightImages` (the app's copy of its logos and photos); `fieldSource` (the `{url, evidence}` schema) |
+| `@trylight/app` | `createApp<typeof contracts>()` → `app.table(entity)` (`list/get/create/update/delete`, `useList/useGet/useCreate/useUpdate/useDelete`, typed by the entity passed), `app.contracts` (`useInvocation`), and `imageSrc(url)` (where a logo or photo loads from) |
+| `@trylight/app/server` | `createLightServer({ schema, contracts })` → `light.db` (Drizzle), `light.session(request)`, `light.signIn(email, password)`, and the route handlers `light.entities`, `light.image`, `light.invoke.handler`, `light.chat` |
 | `@trylight/app/platform` | the door for server functions, framing, analytics/error policies, the pane bridge |
 | `@trylight/app/vite` | `lightDb()`: the dev server syncs `db/schema` into the database on every change |
 | `light-db` (bin) | `sync`, `migrate`, `check`: the app's `pnpm db:*` scripts |
@@ -33,6 +33,17 @@ cached list and row at once and stays pending until the table's refetch lands
 
 Joins and aggregates stay typed server functions over `light.db`.
 
+## Images
+
+`/api/light/image?src=…` serves a logo or photo a row points at from the
+app's own copy in `light_images`: the first view by a member (or any view
+with no sign-in configured) fetches and keeps it, and every later one, and
+the CDN for a year, is the copy. Only public addresses are connected to (checked on the resolved address, each
+redirect hop included); images only (SVG served sandboxed, `nosniff`), size-
+and time-capped. A source that gives no image is a `no-store` 404, so the
+mark shows its letters and the next view asks again. Members-only apps need
+sign-in; a stranger to a public app only reads what members kept.
+
 ## Schema sync
 
 `plan()` diffs `db/schema` against the newest migration snapshot with
@@ -58,4 +69,6 @@ TEST_DATABASE_URL=postgres://you@127.0.0.1:5432/postgres pnpm test   # with the
 pnpm run build                                              # dist/, what the template installs
 ```
 
-Not published yet: the template depends on this directory (`file:`).
+Published to npm; the template installs it from there, so a change here
+reaches new apps once it is published and the template's lockfile takes it.
+To publish: bump `version`, then `pnpm publish` (`prepack` builds `dist`).

package/dist/client.d.ts

@@ -4,6 +4,7 @@ import type { Entity } from "./schema.js";
 export { EntityError, LIST_LIMIT, type ListOptions, type NewRow, type Sort, type Patch, type Row, type Where } from "./entities.js";
 export type { FieldSource, FieldSources } from "./schema.js";
 export { siteOf } from "./schema.js";
+export { imageSrc } from "./images.js";
 export { InvocationError, type InvocationStatus } from "@shubh90/app-runtime/invoke";
 export declare function createApp<C extends Contracts = Record<never, never>>(): {
     table: typeof tableClient;

package/dist/client.js

@@ -12,6 +12,7 @@ import { z } from "zod/v4";
 import { ENTITIES_PATH, EntityError } from "./entities.js";
 export { EntityError, LIST_LIMIT } from "./entities.js";
 export { siteOf } from "./schema.js";
+export { imageSrc } from "./images.js";
 export { InvocationError } from "@shubh90/app-runtime/invoke";
 export function createApp() {
     return { table: tableClient, contracts: createInvoker() };

package/dist/images.d.ts

@@ -0,0 +1,7 @@
+export declare const IMAGE_PATH = "/api/light/image";
+/**
+ * Where a row's photo or logo loads from: the app's own copy (kept from the
+ * first view on) for an address on the web, the value itself for one of the
+ * app's own files.
+ */
+export declare function imageSrc(src: string): string;

package/dist/images.js

@@ -0,0 +1,12 @@
+// What the browser and the image route agree on: where a row's photo or logo
+// loads from. Nothing here may touch a database or the DOM.
+import { webUrl } from "./schema.js";
+export const IMAGE_PATH = "/api/light/image";
+/**
+ * Where a row's photo or logo loads from: the app's own copy (kept from the
+ * first view on) for an address on the web, the value itself for one of the
+ * app's own files.
+ */
+export function imageSrc(src) {
+    return webUrl.safeParse(src).success ? `${IMAGE_PATH}?src=${encodeURIComponent(src)}` : src;
+}

package/dist/schema.d.ts

@@ -1,6 +1,8 @@
 import { PgTable, type PgColumnBuilderBase, type PgTableWithColumns, type PgTableExtraConfigValue } from "drizzle-orm/pg-core";
 import type { BuildColumns, BuildExtraConfigColumns } from "drizzle-orm";
 import { z } from "zod/v4";
+/** An address on the web: http or https. */
+export declare const webUrl: z.ZodURL;
 /** Where one value was read: the page, and the words on it that say so. */
 export declare const fieldSource: z.ZodObject<{
     url: z.ZodURL;
@@ -239,4 +241,86 @@ export declare const lightChanges: PgTableWithColumns<{
     };
     dialect: "pg";
 }>;
+/**
+ * The app's own copy of each photo or logo its rows point at, kept on the
+ * first view (the image route, `@trylight/app/server`), so a source that
+ * moves or shuts down later does not take the picture with it.
+ */
+export declare const lightImages: PgTableWithColumns<{
+    name: "light_images";
+    schema: undefined;
+    columns: {
+        source_url: import("drizzle-orm/pg-core").PgColumn<{
+            name: "source_url";
+            tableName: "light_images";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        content_type: import("drizzle-orm/pg-core").PgColumn<{
+            name: "content_type";
+            tableName: "light_images";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        bytes: import("drizzle-orm/pg-core").PgColumn<{
+            name: "bytes";
+            tableName: "light_images";
+            dataType: "custom";
+            columnType: "PgCustomColumn";
+            data: Uint8Array<ArrayBufferLike>;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            pgColumnBuilderBrand: "PgCustomColumnBuilderBrand";
+        }>;
+        fetched_at: import("drizzle-orm/pg-core").PgColumn<{
+            name: "fetched_at";
+            tableName: "light_images";
+            dataType: "string";
+            columnType: "PgTimestampString";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 export {};

package/dist/schema.js

@@ -3,11 +3,13 @@
 // the app. Imported by drizzle-kit and the browser's types, so nothing here
 // may touch a database or the DOM.
 import { is } from "drizzle-orm";
-import { PgTable, index, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { PgTable, customType, index, jsonb, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
 import { z } from "zod/v4";
+/** An address on the web: http or https. */
+export const webUrl = z.url({ protocol: /^https?$/ });
 /** Where one value was read: the page, and the words on it that say so. */
 export const fieldSource = z.object({
-    url: z.url({ protocol: /^https?$/ }),
+    url: webUrl,
     evidence: z.string().min(1)
 });
 /** The site a source's url names, as people read it: "https://www.acme.com/about" is "acme.com". */
@@ -79,3 +81,15 @@ export const lightChanges = pgTable("light_changes", {
         .notNull()
         .defaultNow()
 }, (t) => [index("light_changes_row_idx").on(t.table_name, t.row_id)]);
+const bytea = customType({ dataType: () => "bytea" });
+/**
+ * The app's own copy of each photo or logo its rows point at, kept on the
+ * first view (the image route, `@trylight/app/server`), so a source that
+ * moves or shuts down later does not take the picture with it.
+ */
+export const lightImages = pgTable("light_images", {
+    source_url: text().primaryKey(),
+    content_type: text().notNull(),
+    bytes: bytea().notNull(),
+    fetched_at: timestamp({ withTimezone: true, mode: "string" }).notNull().defaultNow()
+});

package/dist/server/images.d.ts

@@ -0,0 +1,40 @@
+import { type LookupFunction } from "node:net";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { SessionState } from "./session.js";
+type Db = PostgresJsDatabase<Record<string, unknown>>;
+export declare const MAX_IMAGE_BYTES: number;
+export type StoredImage = {
+    readonly contentType: string;
+    readonly bytes: Uint8Array;
+};
+export type ImageLookup = {
+    readonly ok: true;
+    readonly image: StoredImage;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export type ImageOptions = {
+    db: () => Db;
+    session: (request: Request) => Promise<SessionState>;
+};
+/** `/api/light/image?src=…`: a photo or logo a row points at, served from the app's own copy. */
+export declare function createImageHandler(options: ImageOptions): (request: Request) => Promise<Response>;
+/**
+ * An address on the public internet: not this machine, a private or carrier
+ * network, link-local (the cloud metadata address), multicast or reserved.
+ * An IPv4 address written as IPv6 is judged as itself.
+ */
+export declare function isPublicAddress(address: string): boolean;
+/**
+ * The name lookup of every connection the image fetch opens, redirects
+ * included: the address checked is the address connected to, so a public
+ * name that resolves (or is re-pointed between two asks) to this machine or
+ * a private network is never reached.
+ */
+export declare const publicOnlyLookup: LookupFunction;
+/** The app's copy of the image at `source`, if a member's view has kept one. */
+export declare function keptImage(db: Db, source: URL): Promise<ImageLookup>;
+/** The app's copy of the image at `source`, fetched and kept on the first ask. */
+export declare function storedImage(db: Db, source: URL): Promise<ImageLookup>;
+export {};

package/dist/server/images.js

@@ -0,0 +1,246 @@
+// The app's copy of the photos and logos its rows point at. The first time a
+// member's browser asks the image route for one it is fetched and kept in
+// light_images; every later ask is answered from there, so a source that
+// rate-limits, moves or shuts down after that does not take the picture with
+// it. Ported from the v1 template (#1063).
+import dns from "node:dns";
+import { isIP } from "node:net";
+import { eq } from "drizzle-orm";
+import ipaddr from "ipaddr.js";
+import { Agent } from "undici";
+import { z } from "zod/v4";
+import { lightImages, webUrl } from "../schema.js";
+import { env } from "./env.js";
+const FETCH_TIMEOUT_MS = 15_000;
+const MAX_REDIRECTS = 5;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+export const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+const YEAR_SECONDS = 365 * 24 * 60 * 60;
+// An SVG is a document if someone navigates to it; the route's sandbox
+// header keeps it inert there, and in an <img> it never runs script.
+const IMAGE_TYPES = new Set([
+    "image/png",
+    "image/jpeg",
+    "image/gif",
+    "image/webp",
+    "image/avif",
+    "image/svg+xml",
+    "image/x-icon",
+    "image/vnd.microsoft.icon"
+]);
+// The bytes are an image or they are nothing, and an SVG opened on its own stays inert.
+const INERT = {
+    "Content-Security-Policy": "sandbox",
+    "X-Content-Type-Options": "nosniff"
+};
+// Node's fetch reports a DNS or connection failure as "fetch failed", with the
+// reason (ENOTFOUND, ECONNREFUSED…) only on its cause.
+const networkFailure = z.object({ cause: z.object({ code: z.string() }) });
+/** `/api/light/image?src=…`: a photo or logo a row points at, served from the app's own copy. */
+export function createImageHandler(options) {
+    return async (request) => {
+        const { user, mode } = await options.session(request);
+        if (user === null && mode === "members") {
+            return new Response("Sign in to use this app.", { status: 401 });
+        }
+        const src = webUrl.safeParse(new URL(request.url).searchParams.get("src"));
+        if (!src.success) {
+            return new Response("src must be an http(s) address.", { status: 400 });
+        }
+        const db = options.db();
+        const source = new URL(src.data);
+        // A stranger to a public app only reads the copy, so nobody signed out can
+        // make the app fetch or keep anything; a member's view fills it, as does
+        // every view where there is no sign-in to be a stranger to.
+        const stranger = user === null && env().configured;
+        const lookup = stranger ? keptImage : storedImage;
+        const found = await lookup(db, source);
+        if (!found.ok) {
+            // Nothing is kept for a source that did not answer with an image, so the
+            // next view asks it again; until then the row shows its letters.
+            return new Response(found.reason, {
+                status: 404,
+                headers: { ...INERT, "Cache-Control": "no-store" }
+            });
+        }
+        // Cached by the CDN under the source address, which only someone who
+        // already knows it can ask for; the pictures are the public web's.
+        // A copy: the driver's buffer is typed over any ArrayBufferLike, a body needs one over ArrayBuffer.
+        return new Response(new Uint8Array(found.image.bytes), {
+            headers: {
+                ...INERT,
+                "Content-Type": found.image.contentType,
+                "Cache-Control": `public, max-age=${YEAR_SECONDS}, immutable`
+            }
+        });
+    };
+}
+/**
+ * An address on the public internet: not this machine, a private or carrier
+ * network, link-local (the cloud metadata address), multicast or reserved.
+ * An IPv4 address written as IPv6 is judged as itself.
+ */
+export function isPublicAddress(address) {
+    return ipaddr.isValid(address) && ipaddr.process(address).range() === "unicast";
+}
+class NotPublicAddress extends Error {
+    address;
+    code = "ENOTPUBLIC";
+    constructor(address) {
+        super(`${address} is not a public address.`);
+        this.address = address;
+    }
+}
+/**
+ * The name lookup of every connection the image fetch opens, redirects
+ * included: the address checked is the address connected to, so a public
+ * name that resolves (or is re-pointed between two asks) to this machine or
+ * a private network is never reached.
+ */
+export const publicOnlyLookup = (hostname, options, callback) => {
+    dns.lookup(hostname, options, (error, address, family) => {
+        if (error !== null)
+            return callback(error, address, family);
+        const addresses = Array.isArray(address) ? address.map((found) => found.address) : [address];
+        const [refused = null] = addresses.filter((found) => !isPublicAddress(found));
+        if (refused !== null)
+            return callback(new NotPublicAddress(refused), address, family);
+        callback(null, address, family);
+    });
+};
+// Connects only to public addresses. A bare address in a URL skips the name
+// lookup, so fetchImage checks that one itself.
+const publicWeb = new Agent({ connect: { lookup: publicOnlyLookup } });
+const refusedAddress = z.object({ cause: z.instanceof(NotPublicAddress) });
+// A fragment never reaches the server, so two addresses that differ only
+// there are one image.
+function keyOf(source) {
+    const key = new URL(source);
+    key.hash = "";
+    return key;
+}
+/** The app's copy of the image at `source`, if a member's view has kept one. */
+export async function keptImage(db, source) {
+    const [kept = null] = await db
+        .select({ contentType: lightImages.content_type, bytes: lightImages.bytes })
+        .from(lightImages)
+        .where(eq(lightImages.source_url, keyOf(source).href));
+    if (kept === null)
+        return { ok: false, reason: "No copy of this image is kept yet." };
+    return { ok: true, image: kept };
+}
+/** The app's copy of the image at `source`, fetched and kept on the first ask. */
+export async function storedImage(db, source) {
+    const kept = await keptImage(db, source);
+    if (kept.ok)
+        return kept;
+    const key = keyOf(source);
+    const fetched = await fetchImage(key);
+    if (!fetched.ok)
+        return fetched;
+    await db
+        .insert(lightImages)
+        .values({ source_url: key.href, content_type: fetched.image.contentType, bytes: fetched.image.bytes })
+        .onConflictDoNothing();
+    return fetched;
+}
+function failureReason(error) {
+    const failure = networkFailure.safeParse(error);
+    return failure.success ? failure.data.cause.code : String(error);
+}
+async function fetchImage(source) {
+    const host = source.hostname.toLowerCase();
+    // Each hop is checked: a redirect must never be the way to make this app
+    // fetch from somewhere it would not fetch itself.
+    let url = source;
+    let response;
+    for (let hop = 0;; hop += 1) {
+        const at = url.hostname.toLowerCase();
+        const notPublic = (detail) => ({
+            ok: false,
+            reason: hop === 0
+                ? `${at} is not a public web address${detail}.`
+                : `${host} redirected to ${at}, which is not a public web address${detail}.`
+        });
+        // An IPv6 host is bracketed in a URL.
+        const bare = at.replace(/^\[(.*)\]$/, "$1");
+        if (isIP(bare) !== 0 && !isPublicAddress(bare))
+            return notPublic("");
+        const init = {
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            redirect: "manual",
+            dispatcher: publicWeb
+        };
+        try {
+            response = await fetch(url, init);
+        }
+        catch (error) {
+            const refused = refusedAddress.safeParse(error);
+            if (refused.success)
+                return notPublic(` (it resolves to ${refused.data.cause.address})`);
+            return { ok: false, reason: `${at} could not be reached (${failureReason(error)}).` };
+        }
+        const location = response.headers.get("location");
+        if (location === null || !REDIRECT_STATUSES.has(response.status))
+            break;
+        if (response.body !== null)
+            await response.body.cancel();
+        if (hop === MAX_REDIRECTS)
+            return { ok: false, reason: `${host} redirected too many times.` };
+        url = new URL(location, url);
+    }
+    if (!response.ok)
+        return { ok: false, reason: `${host} answered HTTP ${response.status}.` };
+    const contentType = mediaType(response.headers.get("content-type"));
+    if (!IMAGE_TYPES.has(contentType)) {
+        return { ok: false, reason: `${host} answered with ${contentType || "no content type"}, not an image.` };
+    }
+    let bytes;
+    try {
+        bytes = await readCapped(response, MAX_IMAGE_BYTES);
+    }
+    catch (error) {
+        return { ok: false, reason: `${host} stopped answering before the image was read (${failureReason(error)}).` };
+    }
+    if (bytes === null)
+        return { ok: false, reason: `${host}'s image is over ${MAX_IMAGE_BYTES} bytes.` };
+    // An empty 200 is what a rate-limiter or a CDN edge answers with; kept, it
+    // would be served as the picture for a year.
+    if (bytes.byteLength === 0)
+        return { ok: false, reason: `${host} answered with an empty body.` };
+    return { ok: true, image: { contentType, bytes } };
+}
+/** "image/png; charset=binary" is "image/png"; a response with none has "". */
+function mediaType(header) {
+    if (header === null)
+        return "";
+    return header.replace(/;.*$/, "").trim().toLowerCase();
+}
+// Read at most `limit` bytes, abandoning the response the moment it exceeds
+// them: content-length is advisory, so the cap is applied while reading.
+async function readCapped(response, limit) {
+    const stream = response.body;
+    if (stream === null)
+        return new Uint8Array(0);
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > limit) {
+            await reader.cancel();
+            return null;
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.byteLength;
+    }
+    return out;
+}

package/dist/server/index.d.ts

@@ -18,6 +18,8 @@ export declare function createLightServer<S extends Record<string, unknown>, C e
     readonly db: PostgresJsDatabase<S>;
     /** `/api/light/entities/*`: what `app.table(...)` calls. */
     entities: (request: Request) => Promise<Response>;
+    /** `/api/light/image`: a row's photo or logo, from the app's own copy (kept on the first view). */
+    image: (request: Request) => Promise<Response>;
     /** Server-side starts and reads of the app's contracts. */
     invoke: import("@shubh90/app-runtime/invoke/server").MiiInvoke<C>;
     /** `/api/mii/invoke/*`: the contract buttons, forwarded to Plaza as the person. */

package/dist/server/index.js

@@ -1,6 +1,6 @@
 // The app's server half, bound once in `src/server/light.ts`: its database,
 // its door (sign-in through Plaza), and the routes the SDK serves (entities,
-// contracts, chat). Server-only.
+// images, contracts, chat). Server-only.
 import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
 import { createMiiAuthCore } from "@shubh90/app-runtime/auth/core";
@@ -8,6 +8,7 @@ import { createMiiChatHandler } from "@shubh90/app-runtime/chat/server";
 import { createMiiInvoke } from "@shubh90/app-runtime/invoke/server";
 import { createEntitiesHandler } from "./entities.js";
 import { env } from "./env.js";
+import { createImageHandler } from "./images.js";
 import { readSession, signIn } from "./session.js";
 export { cookieAttributes, safeNext, SESSION_COOKIE } from "@shubh90/app-runtime/auth/core";
 export { defineContracts, InvocationError } from "@shubh90/app-runtime/invoke/server";
@@ -42,6 +43,8 @@ export function createLightServer(options) {
         },
         /** `/api/light/entities/*`: what `app.table(...)` calls. */
         entities: createEntitiesHandler({ schema: options.schema, db, session }),
+        /** `/api/light/image`: a row's photo or logo, from the app's own copy (kept on the first view). */
+        image: createImageHandler({ db, session }),
         /** Server-side starts and reads of the app's contracts. */
         invoke,
         /** `/api/mii/invoke/*`: the contract buttons, forwarded to Plaza as the person. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trylight/app",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The Light SDK every v2 org app depends on: entities (Drizzle tables with a typed client), sign-in, contracts and in-app chat.",
   "license": "UNLICENSED",
   "type": "module",
@@ -54,7 +54,9 @@
     "@shubh90/app-runtime": "^0.10.3",
     "drizzle-kit": "0.31.11",
     "drizzle-zod": "^0.8.3",
-    "tsx": "^4.23.15"
+    "ipaddr.js": "^2.5.0",
+    "tsx": "^4.23.15",
+    "undici": "^7.30.0"
   },
   "devDependencies": {
     "@eslint-community/eslint-plugin-eslint-comments": "^4.8.1",