@trylight/app 0.1.9 → 0.2.1

package/README.md

@@ -2,8 +2,8 @@
 
 The platform half of a v2 org app (`infra/provisioning/org-app-template-v2`):
 its tables and their typed client, its door, its contracts and its chat.
-Sign-in, contracts and chat are `@shubh90/app-runtime`'s, re-exported
-unchanged; entities and the schema sync are new here.
+`src/brand.generated.ts` is baked from `config/brand.json` (`pnpm run brand`;
+`check` fails while it is stale), since the published package cannot read it.
 
 | Import | What |
 |---|---|
@@ -12,7 +12,7 @@ unchanged; entities and the schema sync are new here.
 | `@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; `baseline`: an older app's tables into `db/schema`, once |
+| `light-db` (bin) | `sync`, `migrate`, `check`: the app's `pnpm db:*` scripts |
 
 ## Entities
 
@@ -89,21 +89,6 @@ table` through `mii db write`) is not archived.
 `migrate` installs the functions before applying migrations and the triggers
 after; the template's AGENTS.md has the restore SQL.
 
-## Baseline
-
-`light-db baseline` moves an app made before `db/schema` (the Vite or Next.js
-template, tables made by `migrations/*.sql`) onto it, once: `drizzle-kit pull`
-reads the live database, and `db/migrations/0000_baseline.sql` records the
-tables as they are (its SQL commented out, so migrating runs nothing). A table
-keyed by `id uuid` whose standard columns match becomes an `entity()` file;
-any other stays the plain `pgTable` pull wrote, which no sync changes. The old
-templates' own tables are left in the database. Before writing, it checks the
-files say exactly what the database has; the next sync then only adds the
-`entity()` columns a table lacks and the SDK's `light_*` tables. It refuses,
-writing nothing, a foreign key into a table it leaves out, or an index with a
-non-default operator class. It reads the tables' keys, which Postgres shows
-only to a role with more than SELECT: an app's reader has REFERENCES for it.
-
 ## Develop
 
 ```bash

package/dist/auth/config.d.ts

@@ -0,0 +1,5 @@
+export type MiiAuthConfig = {
+    readonly plazaUrl: string;
+    readonly appId: string;
+};
+export declare function miiAuthConfig(): MiiAuthConfig;

package/dist/auth/config.js

@@ -0,0 +1,16 @@
+// Which app this is and which platform it trusts. Both are injected by the
+// platform (Vercel env + the agent checkout's .env.local) — never set them by
+// hand. MII_ORG_ID is injected too, for the app's own use; sign-in needs only
+// these two.
+import { z } from "zod/v4";
+const env = z.object({
+    MII_PLAZA_URL: z.string().trim().min(1),
+    MII_APP_ID: z.string().trim().min(1)
+});
+export function miiAuthConfig() {
+    const set = env.safeParse(process.env);
+    if (!set.success) {
+        throw new Error("MII_PLAZA_URL and MII_APP_ID are required for sign-in. They are injected at provision time; run `vercel env pull .env.local` locally.");
+    }
+    return { plazaUrl: set.data.MII_PLAZA_URL.replace(/\/+$/, ""), appId: set.data.MII_APP_ID };
+}

package/dist/auth/context.d.ts

@@ -0,0 +1,11 @@
+import type { AuthSql } from "./db.js";
+/**
+ * The per-app binding the db-touching helpers close over: the connection
+ * factory. Built once by `createMiiAuthCore` and threaded in, so nothing here
+ * reads a module-level singleton.
+ */
+export type AuthContext = {
+    readonly getSql: () => Promise<AuthSql>;
+    /** Where the app wants failures that are ours reported (Sentry, etc.). */
+    readonly reportError: (error: unknown, context: Record<string, string>) => void;
+};

package/dist/auth/context.js

@@ -0,0 +1 @@
+export {};

package/dist/auth/core.d.ts

@@ -0,0 +1,64 @@
+import { getAuthMode } from "./mode.js";
+import { safeNext } from "./next-path.js";
+import { SIGN_IN_PROBLEMS } from "./problems.js";
+import { type MiiUser, type ResolvedSession } from "./lookup.js";
+import { type MiiIdentity, type PlazaSession } from "./plaza.js";
+export type { MiiUser, ResolvedSession } from "./lookup.js";
+export type { AuthMode } from "./mode.js";
+export type { MiiIdentity, PlazaSession, SignedIn, SignInFailure, SignInResult } from "./plaza.js";
+export { SIGN_IN_PROBLEMS } from "./problems.js";
+export { safeNext } from "./next-path.js";
+export { SESSION_COOKIE } from "./lookup.js";
+export { signInWithPlaza } from "./plaza.js";
+export type CreateMiiAuthCoreOptions = {
+    /** Where to report failures that are ours, not the person's. Defaults to console.error. */
+    readonly reportError?: (error: unknown, context: Record<string, string>) => void;
+};
+export type MiiAuthCore = {
+    /** The user behind a session token, or null. The app reads its own cookie. */
+    resolveSession(token: string): Promise<MiiUser | null>;
+    /** The same, with the platform token behind the session, for acting as the person. */
+    resolveSessionWithPlaza(token: string): Promise<ResolvedSession | null>;
+    /**
+     * Start a session for the session the platform signed at sign-in; the app sets the
+     * cookie itself (see cookie notes below).
+     */
+    issueSession(userId: string, plaza: PlazaSession): Promise<{
+        token: string;
+        expiresAt: Date;
+    }>;
+    /** End one session by its token. */
+    revokeSession(token: string): Promise<void>;
+    upsertMemberFromIdentity(identity: MiiIdentity): Promise<{
+        id: string;
+        status: string;
+    }>;
+    deactivateUser(userId: string): Promise<void>;
+    /**
+     * The pane's silent sign-in: spend a ?mii_code= for an identity, upsert the
+     * member, start a session. Null when the code is spent/stale or the member
+     * is inactive (send them to /login).
+     */
+    redeemPaneCode(code: string): Promise<{
+        token: string;
+        expiresAt: Date;
+    } | null>;
+    getAuthMode: typeof getAuthMode;
+    readonly SESSION_COOKIE: string;
+    readonly SIGN_IN_PROBLEMS: typeof SIGN_IN_PROBLEMS;
+    readonly safeNext: typeof safeNext;
+};
+/**
+ * Cookie attributes the app must use with issueSession's token: inside the platform's App pane the app is a third party, so the
+ * cookie must be SameSite=None + Secure + partitioned or the pane signs in
+ * forever; opened directly it is an ordinary Lax cookie. Decide by the
+ * request's `Sec-Fetch-Dest: iframe` header.
+ */
+export declare function cookieAttributes(embedded: boolean): {
+    httpOnly: true;
+    path: "/";
+    sameSite: "none" | "lax";
+    secure: boolean;
+    partitioned: boolean;
+};
+export declare function createMiiAuthCore({ reportError }?: CreateMiiAuthCoreOptions): MiiAuthCore;

package/dist/auth/core.js

@@ -0,0 +1,50 @@
+import { makeAuthSql } from "./db.js";
+import { getAuthMode } from "./mode.js";
+import { safeNext } from "./next-path.js";
+import { SIGN_IN_PROBLEMS } from "./problems.js";
+import { issueSession, resolveSession, resolveSessionWithPlaza, revokeSession, SESSION_COOKIE } from "./lookup.js";
+import { redeemWithPlaza } from "./plaza.js";
+import { deactivateUser, upsertMemberFromIdentity } from "./users.js";
+export { SIGN_IN_PROBLEMS } from "./problems.js";
+export { safeNext } from "./next-path.js";
+export { SESSION_COOKIE } from "./lookup.js";
+export { signInWithPlaza } from "./plaza.js";
+/**
+ * Cookie attributes the app must use with issueSession's token: inside the platform's App pane the app is a third party, so the
+ * cookie must be SameSite=None + Secure + partitioned or the pane signs in
+ * forever; opened directly it is an ordinary Lax cookie. Decide by the
+ * request's `Sec-Fetch-Dest: iframe` header.
+ */
+export function cookieAttributes(embedded) {
+    return {
+        httpOnly: true,
+        path: "/",
+        sameSite: embedded ? "none" : "lax",
+        secure: embedded || process.env.NODE_ENV === "production",
+        partitioned: embedded
+    };
+}
+export function createMiiAuthCore({ reportError = (error, context) => console.error("sign-in error", context, error) } = {}) {
+    const ctx = { getSql: makeAuthSql(), reportError };
+    return {
+        resolveSession: (token) => resolveSession(ctx, token),
+        resolveSessionWithPlaza: (token) => resolveSessionWithPlaza(ctx, token),
+        issueSession: (userId, plaza) => issueSession(ctx, userId, plaza),
+        revokeSession: (token) => revokeSession(ctx, token),
+        upsertMemberFromIdentity: (identity) => upsertMemberFromIdentity(ctx, identity),
+        deactivateUser: (userId) => deactivateUser(ctx, userId),
+        redeemPaneCode: async (code) => {
+            const signedIn = await redeemWithPlaza(code);
+            if (signedIn === null)
+                return null;
+            const user = await upsertMemberFromIdentity(ctx, signedIn.identity);
+            if (user.status !== "active")
+                return null;
+            return issueSession(ctx, user.id, signedIn.session);
+        },
+        getAuthMode,
+        SESSION_COOKIE,
+        SIGN_IN_PROBLEMS,
+        safeNext
+    };
+}

package/dist/auth/db.d.ts

@@ -0,0 +1,7 @@
+import postgres from "postgres";
+export type AuthSql = ReturnType<typeof postgres>;
+/**
+ * A connection factory. Memoizes a single pool per process; a failed init (database briefly unreachable) does not wedge
+ * sign-in for the life of the process — the next request tries again.
+ */
+export declare function makeAuthSql(): () => Promise<AuthSql>;

package/dist/auth/db.js

@@ -0,0 +1,57 @@
+// Sign-in's own database access, on the `postgres` driver. Its tables are
+// created on first use, so every app's database has them the first time
+// someone signs in.
+import postgres from "postgres";
+// Idempotent, so a database that already has the tables is untouched.
+const DDL = [
+    `create table if not exists mii_auth_users (
+    id uuid primary key default gen_random_uuid(),
+    mii_id uuid unique,
+    email text,
+    name text not null,
+    avatar_url text,
+    kind text not null default 'member',
+    role text not null default 'member',
+    status text not null default 'active',
+    created_at timestamptz not null default now(),
+    last_login_at timestamptz
+  )`,
+    `create index if not exists mii_auth_users_email_idx on mii_auth_users (email)`,
+    // `kind` marks the org's agents apart from its people; older tables lack it.
+    `alter table mii_auth_users add column if not exists kind text not null default 'member'`,
+    `create table if not exists mii_auth_sessions (
+    token_hash text primary key,
+    user_id uuid not null references mii_auth_users(id) on delete cascade,
+    expires_at timestamptz not null,
+    created_at timestamptz not null default now()
+  )`,
+    `create index if not exists mii_auth_sessions_user_idx on mii_auth_sessions (user_id)`,
+    // The platform's side of a session; older tables lack them.
+    `alter table mii_auth_sessions add column if not exists plaza_token text`,
+    `alter table mii_auth_sessions add column if not exists checked_at timestamptz`
+];
+/**
+ * A connection factory. Memoizes a single pool per process; a failed init (database briefly unreachable) does not wedge
+ * sign-in for the life of the process — the next request tries again.
+ */
+export function makeAuthSql() {
+    let ready = null;
+    return () => {
+        if (ready === null) {
+            ready = (async () => {
+                const url = process.env.DATABASE_URL;
+                if (!url)
+                    throw new Error("DATABASE_URL is required for sign-in.");
+                const client = postgres(url, { prepare: false, max: 2 });
+                for (const statement of DDL) {
+                    await client.unsafe(statement);
+                }
+                return client;
+            })();
+            ready.catch(() => {
+                ready = null;
+            });
+        }
+        return ready;
+    };
+}

package/dist/auth/lookup.d.ts

@@ -0,0 +1,47 @@
+import type { AuthContext } from "./context.js";
+import { type PlazaSession } from "./plaza.js";
+/** The cookie holding this app's own session. Nothing of the platform's is read here. */
+export declare const SESSION_COOKIE = "mii_session";
+/**
+ * How often a session asks the platform whether it still stands. Someone removed from
+ * the org is signed out of the app within this long; their chat stops at once,
+ * because the platform checks membership on every chat request.
+ */
+export declare const SESSION_RECHECK_MS: number;
+export type MiiUser = {
+    readonly id: string;
+    readonly miiId: string | null;
+    readonly name: string;
+    readonly email: string | null;
+    readonly avatarUrl: string | null;
+    readonly role: string;
+};
+/** A session with the platform token behind it, for acting on the platform as the person. */
+export type ResolvedSession = {
+    readonly user: MiiUser;
+    readonly plazaToken: string;
+};
+/**
+ * The user behind a session token, or null. Pure lookup — no request context —
+ * so the proxy can call it with the raw cookie value. A missing, expired, or
+ * deactivated session is null, and so is one the platform no longer stands behind.
+ */
+export declare function resolveSession(ctx: AuthContext, token: string): Promise<MiiUser | null>;
+export declare function resolveSessionWithPlaza(ctx: AuthContext, token: string): Promise<ResolvedSession | null>;
+/**
+ * Start a session and hand back the cookie value to set. It lasts exactly as
+ * long as the session the platform signed. Only the cookie's hash is stored, so a
+ * database read cannot be replayed as a sign-in here; the platform's token is kept as
+ * it is, because this server has to send it, and signing out revokes it.
+ */
+export declare function issueSession(ctx: AuthContext, userId: string, plaza: PlazaSession): Promise<{
+    token: string;
+    expiresAt: Date;
+}>;
+/**
+ * End one session by its cookie value, here and on the platform. The session here ends
+ * whatever the platform says: an unreachable platform is reported, and signing
+ * out still signs out.
+ */
+export declare function revokeSession(ctx: AuthContext, token: string): Promise<void>;
+export declare function hashToken(token: string): string;

package/dist/auth/lookup.js

@@ -0,0 +1,120 @@
+import { createHash, randomBytes } from "node:crypto";
+import { checkPlazaSession, revokePlazaSession } from "./plaza.js";
+/** The cookie holding this app's own session. Nothing of the platform's is read here. */
+export const SESSION_COOKIE = "mii_session";
+/**
+ * How often a session asks the platform whether it still stands. Someone removed from
+ * the org is signed out of the app within this long; their chat stops at once,
+ * because the platform checks membership on every chat request.
+ */
+export const SESSION_RECHECK_MS = 5 * 60 * 1000;
+/**
+ * The user behind a session token, or null. Pure lookup — no request context —
+ * so the proxy can call it with the raw cookie value. A missing, expired, or
+ * deactivated session is null, and so is one the platform no longer stands behind.
+ */
+export async function resolveSession(ctx, token) {
+    const session = await resolveSessionWithPlaza(ctx, token);
+    return session === null ? null : session.user;
+}
+export async function resolveSessionWithPlaza(ctx, token) {
+    const sql = await ctx.getSql();
+    const tokenHash = hashToken(token);
+    const rows = await sql `
+    select u.id, u.mii_id, u.name, u.email, u.avatar_url, u.role,
+           s.plaza_token,
+           (s.checked_at is null or s.checked_at < now() - ${`${SESSION_RECHECK_MS} milliseconds`}::interval) as due
+    from mii_auth_sessions s
+    join mii_auth_users u on u.id = s.user_id
+    where s.token_hash = ${tokenHash}
+      and s.expires_at > now()
+      and s.plaza_token is not null
+      and u.status = 'active'
+    limit 1`;
+    const [row = null] = rows;
+    if (row === null)
+        return null;
+    if (row.due) {
+        const stands = await stillStands(ctx, tokenHash, row.plaza_token);
+        if (!stands) {
+            return null;
+        }
+    }
+    return {
+        user: {
+            id: row.id,
+            miiId: row.mii_id,
+            name: row.name,
+            email: row.email,
+            avatarUrl: row.avatar_url,
+            role: row.role
+        },
+        plazaToken: row.plaza_token
+    };
+}
+/**
+ * Ask the platform whether a session still stands, once per recheck window however
+ * many requests arrive together: the first to claim the window asks, the rest
+ * go on the answer it last had. A session the platform has ended is deleted. The platform
+ * being unreachable is reported and the session kept — an outage there must not
+ * sign every app's people out.
+ */
+async function stillStands(ctx, tokenHash, plazaToken) {
+    const sql = await ctx.getSql();
+    const claimed = await sql `
+    update mii_auth_sessions set checked_at = now()
+    where token_hash = ${tokenHash}
+      and (checked_at is null or checked_at < now() - ${`${SESSION_RECHECK_MS} milliseconds`}::interval)
+    returning token_hash`;
+    if (claimed.length === 0)
+        return true;
+    let answer;
+    try {
+        answer = await checkPlazaSession(plazaToken);
+    }
+    catch (error) {
+        ctx.reportError(error, { where: "sign-in/session", step: "recheck" });
+        return true;
+    }
+    if (answer === "ended") {
+        await sql `delete from mii_auth_sessions where token_hash = ${tokenHash}`;
+        return false;
+    }
+    return true;
+}
+/**
+ * Start a session and hand back the cookie value to set. It lasts exactly as
+ * long as the session the platform signed. Only the cookie's hash is stored, so a
+ * database read cannot be replayed as a sign-in here; the platform's token is kept as
+ * it is, because this server has to send it, and signing out revokes it.
+ */
+export async function issueSession(ctx, userId, plaza) {
+    const token = randomBytes(32).toString("base64url");
+    const sql = await ctx.getSql();
+    await sql `
+    insert into mii_auth_sessions (token_hash, user_id, expires_at, plaza_token, checked_at)
+    values (${hashToken(token)}, ${userId}, ${plaza.expiresAt}, ${plaza.token}, now())`;
+    return { token, expiresAt: plaza.expiresAt };
+}
+/**
+ * End one session by its cookie value, here and on the platform. The session here ends
+ * whatever the platform says: an unreachable platform is reported, and signing
+ * out still signs out.
+ */
+export async function revokeSession(ctx, token) {
+    const sql = await ctx.getSql();
+    const [ended = null] = await sql `
+    delete from mii_auth_sessions where token_hash = ${hashToken(token)}
+    returning plaza_token`;
+    if (ended === null || ended.plaza_token === null)
+        return;
+    try {
+        await revokePlazaSession(ended.plaza_token);
+    }
+    catch (error) {
+        ctx.reportError(error, { where: "sign-in/session", step: "revoke" });
+    }
+}
+export function hashToken(token) {
+    return createHash("sha256").update(token).digest("hex");
+}

package/dist/auth/mode.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod/v4";
+declare const authMode: z.ZodEnum<{
+    public: "public";
+    members: "members";
+}>;
+export type AuthMode = z.infer<typeof authMode>;
+export declare function getAuthMode(): Promise<AuthMode>;
+export {};

package/dist/auth/mode.js

@@ -0,0 +1,52 @@
+import { z } from "zod/v4";
+import { miiAuthConfig } from "./config.js";
+// Who may open this app, as set in the platform (Settings → Workspaces → "Who can open
+// it"). Read from the platform rather than baked into the build so the switch takes
+// effect on the next request, not the next deploy.
+//
+// `public`  — no door; every visitor is anonymous.
+// `members` — only people in the org, who sign in through the platform.
+const authMode = z.enum(["public", "members"]);
+/** What the platform answers about the app: who may open it. */
+const appAuthConfig = z.object({ authMode });
+const TTL_MS = 30_000;
+let cached = null;
+let inflight = null;
+export async function getAuthMode() {
+    if (cached === null || Date.now() - cached.fetchedAt >= TTL_MS) {
+        if (inflight === null) {
+            inflight = fetchMode()
+                .then((mode) => {
+                cached = { mode, fetchedAt: Date.now() };
+            })
+                .catch((error) => {
+                // Keep serving the last known answer through a blip. Only a cold start
+                // with the platform unreachable has nothing to fall back to, and there the door
+                // stays shut rather than swinging open.
+                if (cached === null)
+                    throw error;
+                cached = { ...cached, fetchedAt: Date.now() };
+            })
+                .finally(() => {
+                inflight = null;
+            });
+        }
+        await inflight;
+    }
+    if (cached === null) {
+        throw new Error("Could not reach the platform to check who may open this app.");
+    }
+    return cached.mode;
+}
+async function fetchMode() {
+    const { plazaUrl, appId } = miiAuthConfig();
+    const response = await fetch(`${plazaUrl}/api/app-auth/config?app_id=${encodeURIComponent(appId)}`, { cache: "no-store" });
+    if (!response.ok) {
+        throw new Error(`The platform's app-auth config answered ${response.status}.`);
+    }
+    const config = appAuthConfig.safeParse(await response.json());
+    if (!config.success) {
+        throw new Error("The platform's app-auth config answered with an unexpected shape.");
+    }
+    return config.data.authMode;
+}

package/dist/auth/next-path.d.ts

@@ -0,0 +1 @@
+export declare function safeNext(candidate: string | null): string;

package/dist/auth/next-path.js

@@ -0,0 +1,10 @@
+// Only a path on this app is a valid place to land after signing in. Anything
+// absolute (or protocol-relative) would make the login flow an open redirect.
+export function safeNext(candidate) {
+    if (candidate === null ||
+        !candidate.startsWith("/") ||
+        candidate.startsWith("//")) {
+        return "/";
+    }
+    return candidate;
+}

package/dist/auth/plaza.d.ts

@@ -0,0 +1,68 @@
+/** Who someone is, once the platform has vouched for them. */
+export type MiiIdentity = {
+    readonly miiId: string;
+    readonly orgId: string;
+    readonly email: string | null;
+    readonly name: string;
+    readonly avatarUrl: string | null;
+    /** One of the org's agents, signed in to check the app: not one of its people. */
+    readonly isAgent: boolean;
+};
+/**
+ * The session the platform signs for someone it just signed in. This app keeps the
+ * token on its own session, ends that session when the token expires, and sends
+ * the token back whenever it acts for the person (their chat), so the platform can
+ * check they are still in the org.
+ */
+export type PlazaSession = {
+    readonly token: string;
+    readonly expiresAt: Date;
+};
+/**
+ * Why a sign-in did not happen, in words this app can show as they are.
+ *
+ * `cause` rides along on the failures that are ours rather than the person's
+ * (the platform unreachable, the platform answering nonsense), so the route can report them.
+ */
+export type SignInFailure = {
+    readonly kind: "credentials" | "not_a_member" | "throttled";
+    readonly message: string;
+} | {
+    readonly kind: "unavailable";
+    readonly message: string;
+    readonly cause: unknown;
+};
+export type SignedIn = {
+    readonly identity: MiiIdentity;
+    readonly session: PlazaSession;
+};
+export type SignInResult = ({
+    readonly ok: true;
+} & SignedIn) | {
+    readonly ok: false;
+    readonly failure: SignInFailure;
+};
+/**
+ * Check an email and password with the platform, and get back who the person is and
+ * the session the platform signed for them.
+ */
+export declare function signInWithPlaza(email: string, password: string): Promise<SignInResult>;
+/**
+ * Spend a code for the person behind it, or null if it is spent or stale.
+ *
+ * Throws when the platform itself is the problem — a 5xx or an unreadable answer — so
+ * that reaches the route's error reporting rather than looking like a stale
+ * code and sending the person round again.
+ */
+export declare function redeemWithPlaza(code: string): Promise<SignedIn | null>;
+/**
+ * Whether the platform still stands behind a session: "ended" when the token is no
+ * longer good or the person has left the org. Throws when the platform cannot say, so
+ * an outage is reported rather than read as either answer.
+ */
+export declare function checkPlazaSession(token: string): Promise<"valid" | "ended">;
+/**
+ * Tell the platform a session is over, so the token stops working now rather than when
+ * it expires. Throws when the platform did not take it.
+ */
+export declare function revokePlazaSession(token: string): Promise<void>;