@shubh90/app-runtime 0.1.0

package/README.md

@@ -0,0 +1,129 @@
+# @shubh90/app-runtime
+
+The platform contract every mii org app depends on — **sign-in** and the
+**Next.js config an app must not diverge from** — as a versioned package instead
+of files copied into each app repo on every agent run.
+
+This is Phase 0 + Phase 1 of `docs/handoffs/2026-08-24-platform-runtime-plan.md`:
+replace the kit-sync "vendoring" model (force-overwrite platform files in each
+repo, which caused the fleet-wide `TS2307`, the stuck rebases, and the framing
+white-screens) with a dependency an app installs and pins.
+
+## What's in it
+
+- `@shubh90/app-runtime/auth` — `createMiiAuth()`, the whole sign-in flow (Plaza
+  client, session, the login/logout route handlers, `SIGN_IN_PROBLEMS`,
+  `LOGIN_ACTION`, `safeNext`). Self-contained: it depends only on `postgres`
+  and `next`, never on the app's own code. The app still renders its **own**
+  login page look.
+- `@shubh90/app-runtime/next` — `withMiiPlatform(nextConfig)`, which force-merges the
+  framing headers Plaza's App pane needs so an app cannot forbid its own
+  embedding (the Newmark white-screen bug becomes impossible).
+
+## Why a package (not the kit sync)
+
+A published package physically cannot `import "@/components/..."`, so the
+class of bug where a synced login page imported an app UI component it lacked is
+gone. Nothing is written into the app's tree each run, so the tree stays clean
+and autosave never fights a kit-dirtied tree. Apps pin a version; a breaking
+Plaza contract change is a semver major with a deprecation window, not a flag
+day.
+
+## Publishing (GitHub Packages)
+
+Built and published from the monorepo on a `app-runtime-v*` tag by
+`.github/workflows/publish-app-runtime.yml`. The registry is
+`npm.pkg.github.com`, scope `@mii`.
+
+```bash
+# maintainers, from packages/app-runtime:
+npm version patch          # or minor / major
+git tag app-runtime-v$(node -p "require('./package.json').version")
+git push --tags            # CI builds and publishes
+```
+
+## Installing in an org app
+
+Add an `.npmrc` to the app repo so `@mii` resolves to GitHub Packages,
+authenticated by the token the app's build already has:
+
+```
+@shubh9:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+Then:
+
+```bash
+npm install @shubh90/app-runtime
+```
+
+## Wiring it up (what each app file becomes)
+
+**One binding** (`src/lib/mii-auth.ts`) — this is where the old `tables.ts`
+config goes now:
+
+```ts
+import { createMiiAuth } from "@shubh90/app-runtime/auth";
+import * as Sentry from "@sentry/nextjs"; // optional
+
+export const auth = createMiiAuth({
+  // Only if the app kept a pre-kit user table (CBRE, Newmark, WBP):
+  // users: { table: "user", idFrom: "kit", emailRequired: true, adoptByEmail: true, ensureSchema: false, insertDefaults: { emailVerified: false } },
+  reportError: (error, tags) => Sentry.captureException(error, { tags })
+});
+```
+
+**The route handlers** become one line each:
+
+```ts
+// src/app/api/mii-auth/login/route.ts
+import { auth } from "@/lib/mii-auth";
+export const dynamic = "force-dynamic";
+export const POST = (request: Request) => auth.loginRoute(request);
+
+// src/app/api/mii-auth/logout/route.ts
+import { auth } from "@/lib/mii-auth";
+export const dynamic = "force-dynamic";
+export const POST = () => auth.logoutRoute();
+```
+
+**Guarding pages** (`getUser` / `requireUser` as before):
+
+```ts
+import { auth } from "@/lib/mii-auth";
+const user = await auth.requireUser();   // in the authenticated layout
+const user = await auth.getUser();       // in API routes: MiiUser | null
+```
+
+**The login page** stays the app's own look. It reads the pieces from the
+binding rather than a copied `problems.ts` / route:
+
+```tsx
+import { auth } from "@/lib/mii-auth";
+const problem = params.error ? auth.SIGN_IN_PROBLEMS[params.error] : null;
+// <form method="post" action={auth.LOGIN_ACTION}> ... </form>
+```
+
+**next.config** wraps the app's own config:
+
+```js
+import { withMiiPlatform } from "@shubh90/app-runtime/next";
+export default withMiiPlatform({ /* the app's own next config */ });
+```
+
+## Migration order (rollout)
+
+See the plan doc. In short: publish `@shubh90/app-runtime`, convert one app on a
+test org and prove sign-in in the pane, then a version-bump bot adopts it across
+the fleet, then delete `syncPlatformKit` / `PLATFORM_OWNED_PREFIXES` and the
+`backfill-org-app-*` scripts.
+
+## Parity with the kit it replaces
+
+The auth logic is ported verbatim from
+`infra/provisioning/org-app-template/src/lib/mii-auth`; only the module-level
+`USERS`/`authSql` singletons became a `createMiiAuth` argument, and the login
+route's hard `@sentry/nextjs` import became the injected `reportError`. The
+existing `next-path` and `plaza` unit tests are ported (`test/`), plus new
+coverage for `withMiiPlatform` and the users config.

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,12 @@
+// Which app this is and which Plaza 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.
+export function miiAuthConfig() {
+    const plazaUrl = process.env.MII_PLAZA_URL?.trim().replace(/\/+$/, "");
+    const appId = process.env.MII_APP_ID?.trim();
+    if (!plazaUrl || !appId) {
+        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, appId };
+}

package/dist/auth/context.d.ts

@@ -0,0 +1,14 @@
+import type { AuthSql } from "./db.js";
+import type { ResolvedUsers } from "./users-config.js";
+/**
+ * The per-app binding the db-touching helpers close over: the connection
+ * factory and the resolved user-table config. Built once by `createMiiAuth`
+ * and threaded in, so nothing here reads a module-level singleton — the reason
+ * this became a package instead of files copied into every repo.
+ */
+export type AuthContext = {
+    readonly getSql: () => Promise<AuthSql>;
+    readonly users: ResolvedUsers;
+    /** 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/db.d.ts

@@ -0,0 +1,9 @@
+import postgres from "postgres";
+import type { ResolvedUsers } from "./users-config.js";
+export type AuthSql = ReturnType<typeof postgres>;
+/**
+ * A connection factory bound to one app's user config. 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(users: ResolvedUsers): () => Promise<AuthSql>;

package/dist/auth/db.js

@@ -0,0 +1,62 @@
+// The kit's own database access, on the one dependency every org app has: the
+// `postgres` driver. No Drizzle, no imports from the rest of the app — apps
+// cut from older templates (no src/db/schema.ts, no drizzle-orm installed)
+// still sign in, which is the point.
+//
+// The tables are created on first use with the same statements
+// migrations/0004_mii_auth.sql ships, so an app whose database predates that
+// migration heals itself the first time someone signs in — unless the app
+// brought its own user table (UsersConfig), which has its own migrations.
+import postgres from "postgres";
+// Verbatim from migrations/0004_mii_auth.sql (keep the two in step):
+// 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)`,
+    `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)`
+];
+/**
+ * A connection factory bound to one app's user config. 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(users) {
+    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 });
+                if (users.ensureSchema) {
+                    for (const statement of DDL) {
+                        await client.unsafe(statement);
+                    }
+                }
+                return client;
+            })();
+            ready.catch(() => {
+                ready = null;
+            });
+        }
+        return ready;
+    };
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,38 @@
+import { getAuthMode } from "./mode.js";
+import { safeNext } from "./next-path.js";
+import { SIGN_IN_PROBLEMS } from "./problems.js";
+import { type MiiUser } from "./lookup.js";
+import { type UsersConfig } from "./users-config.js";
+export type { MiiUser } from "./lookup.js";
+export type { AuthMode } from "./mode.js";
+export type { MiiIdentity } from "./plaza.js";
+export type { UsersConfig } from "./users-config.js";
+export { SIGN_IN_PROBLEMS } from "./problems.js";
+export { safeNext } from "./next-path.js";
+export { SESSION_COOKIE } from "./lookup.js";
+export type CreateMiiAuthOptions = {
+    /** Which table holds this app's people, if not the default `mii_auth_users`. */
+    readonly users?: UsersConfig;
+    /**
+     * Where to report failures that are ours, not the person's (Plaza down, a
+     * refused write). Wire it to Sentry: `reportError: (e, tags) =>
+     * Sentry.captureException(e, { tags })`. Defaults to console.error.
+     */
+    readonly reportError?: (error: unknown, context: Record<string, string>) => void;
+};
+export type MiiAuth = {
+    getUser(): Promise<MiiUser | null>;
+    requireUser(): Promise<MiiUser | null>;
+    createSession(userId: string): Promise<void>;
+    destroySession(): Promise<void>;
+    resolveSession(token: string): Promise<MiiUser | null>;
+    deactivateUser(userId: string): Promise<void>;
+    getAuthMode: typeof getAuthMode;
+    loginRoute(request: Request): Promise<Response>;
+    logoutRoute(): Promise<Response>;
+    readonly SESSION_COOKIE: string;
+    readonly LOGIN_ACTION: string;
+    readonly SIGN_IN_PROBLEMS: typeof SIGN_IN_PROBLEMS;
+    readonly safeNext: typeof safeNext;
+};
+export declare function createMiiAuth(options?: CreateMiiAuthOptions): MiiAuth;

package/dist/auth/index.js

@@ -0,0 +1,36 @@
+import { makeAuthSql } from "./db.js";
+import { getAuthMode } from "./mode.js";
+import { safeNext } from "./next-path.js";
+import { SIGN_IN_PROBLEMS } from "./problems.js";
+import { loginRoute, logoutRoute, LOGIN_ACTION } from "./routes.js";
+import { createSession, destroySession, getUser, requireUser } from "./session.js";
+import { resolveSession, SESSION_COOKIE } from "./lookup.js";
+import { deactivateUser } from "./users.js";
+import { resolveUsers } from "./users-config.js";
+export { SIGN_IN_PROBLEMS } from "./problems.js";
+export { safeNext } from "./next-path.js";
+export { SESSION_COOKIE } from "./lookup.js";
+export function createMiiAuth(options = {}) {
+    const users = resolveUsers(options.users);
+    const ctx = {
+        getSql: makeAuthSql(users),
+        users,
+        reportError: options.reportError ??
+            ((error, context) => console.error("mii-auth error", context, error))
+    };
+    return {
+        getUser: () => getUser(ctx),
+        requireUser: () => requireUser(ctx),
+        createSession: (userId) => createSession(ctx, userId),
+        destroySession: () => destroySession(ctx),
+        resolveSession: (token) => resolveSession(ctx, token),
+        deactivateUser: (userId) => deactivateUser(ctx, userId),
+        getAuthMode,
+        loginRoute: (request) => loginRoute(ctx, request),
+        logoutRoute: () => logoutRoute(ctx),
+        SESSION_COOKIE,
+        LOGIN_ACTION,
+        SIGN_IN_PROBLEMS,
+        safeNext
+    };
+}

package/dist/auth/lookup.d.ts

@@ -0,0 +1,36 @@
+import type { AuthContext } from "./context.js";
+/** The cookie holding this app's own session. Nothing of Plaza's is read here. */
+export declare const SESSION_COOKIE = "mii_session";
+/**
+ * A week.
+ *
+ * This app holds its own sessions now, so signing in means a password typed on
+ * its own page rather than a silent hop through a session Plaza already had —
+ * which makes a short life felt. A week is one sign-in most people notice once.
+ * Someone removed from the org keeps this app until their session runs out, so
+ * deactivate them here when it has to be immediate.
+ */
+export declare const SESSION_TTL_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;
+};
+/**
+ * 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.
+ */
+export declare function resolveSession(ctx: AuthContext, token: string): Promise<MiiUser | null>;
+/**
+ * Start a session and hand back the cookie value to set. Only the hash is
+ * stored, so a database read cannot be replayed as a sign-in.
+ */
+export declare function issueSession(ctx: AuthContext, userId: string): Promise<{
+    token: string;
+    expiresAt: Date;
+}>;
+export declare function hashToken(token: string): string;

package/dist/auth/lookup.js

@@ -0,0 +1,56 @@
+import { createHash, randomBytes } from "node:crypto";
+/** The cookie holding this app's own session. Nothing of Plaza's is read here. */
+export const SESSION_COOKIE = "mii_session";
+/**
+ * A week.
+ *
+ * This app holds its own sessions now, so signing in means a password typed on
+ * its own page rather than a silent hop through a session Plaza already had —
+ * which makes a short life felt. A week is one sign-in most people notice once.
+ * Someone removed from the org keeps this app until their session runs out, so
+ * deactivate them here when it has to be immediate.
+ */
+export const SESSION_TTL_MS = 7 * 24 * 60 * 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.
+ */
+export async function resolveSession(ctx, token) {
+    const sql = await ctx.getSql();
+    const rows = await sql `
+    select u.id, u.mii_id, u.name, u.email, u.${sql(ctx.users.avatarColumn)} as avatar_url, u.role
+    from mii_auth_sessions s
+    join ${sql(ctx.users.table)} u on u.id = s.user_id
+    where s.token_hash = ${hashToken(token)}
+      and s.expires_at > now()
+      and u.status = 'active'
+    limit 1`;
+    const row = rows[0];
+    if (row === undefined)
+        return null;
+    return {
+        id: row.id,
+        miiId: row.mii_id,
+        name: row.name,
+        email: row.email,
+        avatarUrl: row.avatar_url,
+        role: row.role
+    };
+}
+/**
+ * Start a session and hand back the cookie value to set. Only the hash is
+ * stored, so a database read cannot be replayed as a sign-in.
+ */
+export async function issueSession(ctx, userId) {
+    const token = randomBytes(32).toString("base64url");
+    const expiresAt = new Date(Date.now() + SESSION_TTL_MS);
+    const sql = await ctx.getSql();
+    await sql `
+    insert into mii_auth_sessions (token_hash, user_id, expires_at)
+    values (${hashToken(token)}, ${userId}, ${expiresAt})`;
+    return { token, expiresAt };
+}
+export function hashToken(token) {
+    return createHash("sha256").update(token).digest("hex");
+}

package/dist/auth/mode.d.ts

@@ -0,0 +1,2 @@
+export type AuthMode = "public" | "members";
+export declare function getAuthMode(): Promise<AuthMode>;

package/dist/auth/mode.js

@@ -0,0 +1,40 @@
+import { miiAuthConfig } from "./config.js";
+const TTL_MS = 30_000;
+let cached = null;
+let inflight = null;
+export async function getAuthMode() {
+    if (cached === null || Date.now() - cached.fetchedAt >= TTL_MS) {
+        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 Plaza 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 Plaza 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(`Plaza app-auth config answered ${response.status}.`);
+    }
+    const body = (await response.json());
+    if (body.authMode !== "public" && body.authMode !== "members") {
+        throw new Error("Plaza app-auth config answered with an unexpected shape.");
+    }
+    return body.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,46 @@
+/** Who someone is, once Plaza has vouched for them. */
+export type MiiIdentity = {
+    readonly miiId: string;
+    readonly orgId: string;
+    readonly email: string | null;
+    readonly name: string;
+    readonly avatarUrl: string | null;
+};
+/**
+ * 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
+ * (Plaza unreachable, Plaza answering nonsense), so the route can report them:
+ * a sign-in that fails because of us and tells nobody is the failure mode this
+ * kit replaced.
+ */
+export type SignInFailure = {
+    readonly kind: "credentials" | "not_a_member" | "throttled" | "unavailable";
+    readonly message: string;
+    readonly cause?: unknown;
+};
+export type SignInResult = {
+    readonly ok: true;
+    readonly identity: MiiIdentity;
+} | {
+    readonly ok: false;
+    readonly failure: SignInFailure;
+};
+/**
+ * Check an email and password with Plaza, and get back who the person is.
+ *
+ * One round trip. It used to be two — a code, then a redeem — which doubled
+ * the wait on a form submit for nothing: this server is the only party on the
+ * line and is trusted to hold the answer. The code path still exists for the
+ * App pane, where a browser carries it.
+ */
+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 Plaza 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<MiiIdentity | null>;
+export declare function failureFor(status: number, body: string): SignInFailure;

package/dist/auth/plaza.js

@@ -0,0 +1,111 @@
+import { miiAuthConfig } from "./config.js";
+/**
+ * Check an email and password with Plaza, and get back who the person is.
+ *
+ * One round trip. It used to be two — a code, then a redeem — which doubled
+ * the wait on a form submit for nothing: this server is the only party on the
+ * line and is trusted to hold the answer. The code path still exists for the
+ * App pane, where a browser carries it.
+ */
+export async function signInWithPlaza(email, password) {
+    const { plazaUrl, appId } = miiAuthConfig();
+    let response;
+    try {
+        response = await fetch(`${plazaUrl}/api/app-auth/sign-in`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ appId, email, password }),
+            cache: "no-store"
+        });
+    }
+    catch (cause) {
+        return {
+            ok: false,
+            failure: {
+                kind: "unavailable",
+                message: "Sign-in is unreachable right now. Try again in a moment.",
+                cause
+            }
+        };
+    }
+    if (response.ok) {
+        const body = (await response.json());
+        const identity = asIdentity(body);
+        if (identity !== null) {
+            return { ok: true, identity };
+        }
+        return {
+            ok: false,
+            failure: {
+                kind: "unavailable",
+                message: "Sign-in answered with something unexpected. Try again.",
+                cause: new Error(`Plaza sign-in answered 200 without an identity: ${JSON.stringify(body)}`)
+            }
+        };
+    }
+    return { ok: false, failure: failureFor(response.status, await response.text()) };
+}
+/**
+ * Spend a code for the person behind it, or null if it is spent or stale.
+ *
+ * Throws when Plaza 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 async function redeemWithPlaza(code) {
+    const { plazaUrl, appId } = miiAuthConfig();
+    const response = await fetch(`${plazaUrl}/api/app-auth/redeem`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ appId, code }),
+        cache: "no-store"
+    });
+    if (response.status >= 500) {
+        throw new Error(`Plaza redeem answered ${response.status}: ${await response.text()}`);
+    }
+    if (!response.ok) {
+        return null;
+    }
+    const body = (await response.json());
+    const identity = asIdentity(body);
+    if (identity === null) {
+        throw new Error(`Plaza redeem answered 200 without an identity: ${JSON.stringify(body)}`);
+    }
+    return identity;
+}
+function asIdentity(body) {
+    if (typeof body.miiId !== "string" || typeof body.name !== "string") {
+        return null;
+    }
+    return {
+        miiId: body.miiId,
+        orgId: typeof body.orgId === "string" ? body.orgId : "",
+        email: typeof body.email === "string" ? body.email : null,
+        name: body.name,
+        avatarUrl: typeof body.avatarUrl === "string" ? body.avatarUrl : null
+    };
+}
+export function failureFor(status, body) {
+    if (status === 401) {
+        return { kind: "credentials", message: "Wrong email or password." };
+    }
+    if (status === 403) {
+        return {
+            kind: "not_a_member",
+            // Said plainly: they have just proved they own the account, so this is
+            // not a secret from them, and it is the one thing they can act on.
+            message: "That account isn't set up for this app. Ask whoever runs it."
+        };
+    }
+    if (status === 429) {
+        return {
+            kind: "throttled",
+            message: "Too many wrong tries. Wait a minute and try again."
+        };
+    }
+    return {
+        kind: "unavailable",
+        message: "Sign-in isn't answering right now. Try again in a moment.",
+        cause: new Error(`Plaza sign-in answered ${status}: ${body.slice(0, 300)}`)
+    };
+}

package/dist/auth/problems.d.ts

@@ -0,0 +1,4 @@
+export declare const SIGN_IN_PROBLEMS: Record<string, {
+    readonly title: string;
+    readonly body: string;
+}>;

package/dist/auth/problems.js

@@ -0,0 +1,36 @@
+// Why a sign-in did not happen, in words worth reading.
+//
+// The code travels in the URL and the words live here, so a failure never puts
+// an email, a password, or a message Plaza wrote into someone's address bar or
+// their history. Each one says what to do next, because "try again" is only the
+// right advice for some of them.
+export const SIGN_IN_PROBLEMS = {
+    credentials: {
+        title: "Wrong email or password",
+        body: "Check both and try again. It's the same account you use for mii."
+    },
+    not_a_member: {
+        title: "That account can't open this app",
+        body: "The password was right, but the account isn't in this app's org. Ask whoever runs it to add you."
+    },
+    deactivated: {
+        title: "Your access here has been turned off",
+        body: "Ask whoever runs this app to turn it back on."
+    },
+    throttled: {
+        title: "Too many wrong tries",
+        body: "Wait a minute, then try again."
+    },
+    expired: {
+        title: "That took too long",
+        body: "The sign-in expired before it finished. Try again."
+    },
+    unavailable: {
+        title: "Sign-in isn't answering",
+        body: "This is our side, not yours. Try again in a moment."
+    },
+    missing: {
+        title: "Enter your email and password",
+        body: "Both are needed to sign in."
+    }
+};

package/dist/auth/routes.d.ts

@@ -0,0 +1,19 @@
+import type { AuthContext } from "./context.js";
+/** What the login form posts to. Exported so an app's page can build its form. */
+export declare const LOGIN_ACTION = "/api/mii-auth/login";
+/**
+ * The login route handler. The password goes to Plaza, which owns it, and comes
+ * back as a code this server spends for who the person is. Nothing is kept here
+ * but the session that results — and that session is this app's alone.
+ *
+ * Answers a form post with a redirect and a JSON post with JSON, so the page
+ * works with no JavaScript and a script can still sign in. Every failure that
+ * is ours — Plaza down, a database write refused, anything thrown — is handed
+ * to `ctx.reportError` before the person sees "our side, try again".
+ */
+export declare function loginRoute(ctx: AuthContext, request: Request): Promise<Response>;
+/**
+ * The logout route handler. Signs out of this app, and only this app. POST
+ * only: a GET that signs you out is a link someone else can make you click.
+ */
+export declare function logoutRoute(ctx: AuthContext): Promise<Response>;

package/dist/auth/routes.js

@@ -0,0 +1,108 @@
+import { NextResponse } from "next/server";
+import { safeNext } from "./next-path.js";
+import { signInWithPlaza } from "./plaza.js";
+import { createSession, destroySession } from "./session.js";
+import { upsertMemberFromIdentity } from "./users.js";
+/** What the login form posts to. Exported so an app's page can build its form. */
+export const LOGIN_ACTION = "/api/mii-auth/login";
+// What a caller that reads status codes should see. Only the form path renders
+// words; a script needs "wrong password" and "slow down" to be different
+// answers, which they are not if everything that is not our fault is a 401.
+const STATUS_FOR = {
+    credentials: 401,
+    not_a_member: 403,
+    throttled: 429,
+    unavailable: 503
+};
+/**
+ * The login route handler. The password goes to Plaza, which owns it, and comes
+ * back as a code this server spends for who the person is. Nothing is kept here
+ * but the session that results — and that session is this app's alone.
+ *
+ * Answers a form post with a redirect and a JSON post with JSON, so the page
+ * works with no JavaScript and a script can still sign in. Every failure that
+ * is ours — Plaza down, a database write refused, anything thrown — is handed
+ * to `ctx.reportError` before the person sees "our side, try again".
+ */
+export async function loginRoute(ctx, request) {
+    // A JSON post answers with JSON (a script signing in); a form post answers
+    // with a redirect (the page working with no JavaScript).
+    const isForm = !request.headers
+        .get("content-type")
+        ?.includes("application/json");
+    let body;
+    if (isForm) {
+        // forEach is on FormData in both the DOM and Node typings; iterating it
+        // directly is not, and this package builds against Node's lib.
+        const fields = {};
+        (await request.formData()).forEach((value, key) => {
+            fields[key] = value;
+        });
+        body = fields;
+    }
+    else {
+        body = (await request.json().catch(() => null));
+    }
+    const email = typeof body?.email === "string" ? body.email.trim() : "";
+    const password = typeof body?.password === "string" ? body.password : "";
+    const next = safeNext(typeof body?.next === "string" ? body.next : null);
+    const answer = (problem, status) => problem === null
+        ? isForm
+            ? seeOther(next)
+            : NextResponse.json({ ok: true })
+        : isForm
+            ? seeOther(loginPath(next, problem))
+            : NextResponse.json({ error: problem }, { status });
+    if (email === "" || password === "") {
+        return answer("missing", 400);
+    }
+    try {
+        const attempt = await signInWithPlaza(email, password);
+        if (!attempt.ok) {
+            if (attempt.failure.cause !== undefined) {
+                ctx.reportError(attempt.failure.cause, {
+                    where: "mii-auth/login",
+                    step: "sign-in"
+                });
+            }
+            return answer(attempt.failure.kind, STATUS_FOR[attempt.failure.kind]);
+        }
+        const user = await upsertMemberFromIdentity(ctx, attempt.identity);
+        if (user.status !== "active") {
+            // A real member of the org whose access to THIS app was turned off here.
+            // Plaza has no idea; this is the app's own switch.
+            return answer("deactivated", 403);
+        }
+        await createSession(ctx, user.id);
+        return answer(null, 200);
+    }
+    catch (error) {
+        ctx.reportError(error, { where: "mii-auth/login", step: "session" });
+        console.error("mii-auth: sign-in failed on our side", error);
+        return answer("unavailable", 503);
+    }
+}
+/**
+ * The logout route handler. Signs out of this app, and only this app. POST
+ * only: a GET that signs you out is a link someone else can make you click.
+ */
+export async function logoutRoute(ctx) {
+    await destroySession(ctx);
+    return new NextResponse(null, {
+        status: 303,
+        headers: { Location: "/login" }
+    });
+}
+/** Back to the form, carrying only a code — never an address or a password. */
+function loginPath(next, problem) {
+    const query = new URLSearchParams({ next, error: problem });
+    return `/login?${query.toString()}`;
+}
+/**
+ * A redirect to a path on this app, with no host in it. An absolute one would
+ * be built from `request.url`, and inside Plaza's App pane this process is
+ * reached on the VM's own loopback address — a machine the browser is not.
+ */
+function seeOther(path) {
+    return new NextResponse(null, { status: 303, headers: { Location: path } });
+}

package/dist/auth/session.d.ts

@@ -0,0 +1,35 @@
+import type { AuthContext } from "./context.js";
+import { type MiiUser } from "./lookup.js";
+/**
+ * The signed-in user, or null. Use in API routes and anywhere "who is this, if
+ * anyone" is the question. For pages that need a person, prefer requireUser().
+ */
+export declare function getUser(ctx: AuthContext): Promise<MiiUser | null>;
+/**
+ * The signed-in user when the app has a door; null when it is public.
+ *
+ * Call this in the authenticated layout. If the app is members-only and nobody
+ * is signed in, this never returns — it sends the browser to /login. When the
+ * app is public it returns null and your pages render for an anonymous visitor.
+ */
+export declare function requireUser(ctx: AuthContext): Promise<MiiUser | null>;
+/** Start a session for a user and set its cookie. */
+export declare function createSession(ctx: AuthContext, userId: string): Promise<void>;
+/** End the current session, if any, and clear its cookie. */
+export declare function destroySession(ctx: AuthContext): Promise<void>;
+/**
+ * Cookie attributes for this request.
+ *
+ * Plaza shows this app inside an iframe on its own page. There the app is a
+ * third party, and a Lax cookie is simply not sent — so the pane would sign in
+ * forever. Inside a frame the cookie is SameSite=None and *partitioned*: keyed
+ * to the page framing it. Opened directly, it is an ordinary Lax first-party
+ * cookie. `Sec-Fetch-Dest: iframe` is how the browser tells us which case it is.
+ */
+export declare function cookieOptions(): Promise<{
+    httpOnly: boolean;
+    path: string;
+    sameSite: "none" | "lax";
+    secure: boolean;
+    partitioned: boolean;
+}>;

package/dist/auth/session.js

@@ -0,0 +1,68 @@
+import { cookies, headers } from "next/headers";
+import { redirect } from "next/navigation";
+import { hashToken, issueSession, resolveSession, SESSION_COOKIE } from "./lookup.js";
+import { getAuthMode } from "./mode.js";
+import { safeNext } from "./next-path.js";
+/**
+ * The signed-in user, or null. Use in API routes and anywhere "who is this, if
+ * anyone" is the question. For pages that need a person, prefer requireUser().
+ */
+export async function getUser(ctx) {
+    const token = (await cookies()).get(SESSION_COOKIE)?.value;
+    return token === undefined ? null : resolveSession(ctx, token);
+}
+/**
+ * The signed-in user when the app has a door; null when it is public.
+ *
+ * Call this in the authenticated layout. If the app is members-only and nobody
+ * is signed in, this never returns — it sends the browser to /login. When the
+ * app is public it returns null and your pages render for an anonymous visitor.
+ */
+export async function requireUser(ctx) {
+    const user = await getUser(ctx);
+    if (user !== null) {
+        return user;
+    }
+    if ((await getAuthMode()) === "public") {
+        return null;
+    }
+    const path = (await headers()).get("x-mii-pathname") ?? "/";
+    redirect(`/login?next=${encodeURIComponent(safeNext(path))}`);
+}
+/** Start a session for a user and set its cookie. */
+export async function createSession(ctx, userId) {
+    const { token, expiresAt } = await issueSession(ctx, userId);
+    (await cookies()).set(SESSION_COOKIE, token, {
+        ...(await cookieOptions()),
+        expires: expiresAt
+    });
+}
+/** End the current session, if any, and clear its cookie. */
+export async function destroySession(ctx) {
+    const store = await cookies();
+    const token = store.get(SESSION_COOKIE)?.value;
+    if (token !== undefined) {
+        const sql = await ctx.getSql();
+        await sql `delete from mii_auth_sessions where token_hash = ${hashToken(token)}`;
+        store.set(SESSION_COOKIE, "", { ...(await cookieOptions()), maxAge: 0 });
+    }
+}
+/**
+ * Cookie attributes for this request.
+ *
+ * Plaza shows this app inside an iframe on its own page. There the app is a
+ * third party, and a Lax cookie is simply not sent — so the pane would sign in
+ * forever. Inside a frame the cookie is SameSite=None and *partitioned*: keyed
+ * to the page framing it. Opened directly, it is an ordinary Lax first-party
+ * cookie. `Sec-Fetch-Dest: iframe` is how the browser tells us which case it is.
+ */
+export async function cookieOptions() {
+    const embedded = (await headers()).get("sec-fetch-dest") === "iframe";
+    return {
+        httpOnly: true,
+        path: "/",
+        sameSite: embedded ? "none" : "lax",
+        secure: embedded || process.env.NODE_ENV === "production",
+        partitioned: embedded
+    };
+}

package/dist/auth/users-config.d.ts

@@ -0,0 +1,29 @@
+export type UsersConfig = {
+    /** The table. Quoted by the kit, so `"user"` is fine. */
+    table?: string;
+    /**
+     * Who makes a new row's id. "database" — the column has a default (uuid).
+     * "kit" — the column has none (Better Auth's text ids), so the kit passes one.
+     */
+    idFrom?: "database" | "kit";
+    /** Column holding the avatar URL. */
+    avatarColumn?: string;
+    /** Column stamped on every sign-in. */
+    lastLoginColumn?: string;
+    /** Columns a fresh row needs that Plaza does not supply, with their values. */
+    insertDefaults?: Record<string, string | number | boolean>;
+    /** The table's `email` is NOT NULL, so the kit fills one in when needed. */
+    emailRequired?: boolean;
+    /**
+     * Rows created before the person had a mii id (an app older than the kit) are
+     * matched by address on first sign-in and given their mii id, not duplicated.
+     */
+    adoptByEmail?: boolean;
+    /**
+     * Run the kit's own CREATE TABLE IF NOT EXISTS on first use. Only right for
+     * the default table; an app-owned table has its own migrations.
+     */
+    ensureSchema?: boolean;
+};
+export type ResolvedUsers = Required<UsersConfig>;
+export declare function resolveUsers(config: UsersConfig | undefined): ResolvedUsers;

package/dist/auth/users-config.js

@@ -0,0 +1,22 @@
+// Where an app keeps its people. This used to be `src/lib/mii-auth/tables.ts`,
+// the one file the kit was forbidden to overwrite — because the kit's logic is
+// the platform's, but which table holds the users is the app's. As a package,
+// that seam is a config argument to `createMiiAuth` instead of a file the sync
+// had to carve out and never touch.
+//
+// Three apps (CBRE Toronto, Newmark SF, WBP) kept Better Auth's `"user"` table
+// as their own; they pass `{ table: "user", idFrom: "kit", ... }`. Everyone
+// else takes the default (`mii_auth_users`, shipped by migrations/0004).
+const DEFAULTS = {
+    table: "mii_auth_users",
+    idFrom: "database",
+    avatarColumn: "avatar_url",
+    lastLoginColumn: "last_login_at",
+    insertDefaults: {},
+    emailRequired: false,
+    adoptByEmail: false,
+    ensureSchema: true
+};
+export function resolveUsers(config) {
+    return { ...DEFAULTS, ...(config ?? {}) };
+}

package/dist/auth/users.d.ts

@@ -0,0 +1,8 @@
+import type { AuthContext } from "./context.js";
+import type { MiiIdentity } from "./plaza.js";
+export declare function upsertMemberFromIdentity(ctx: AuthContext, identity: MiiIdentity): Promise<{
+    id: string;
+    status: string;
+}>;
+/** Deactivate a user: their sessions stop working on the next request. */
+export declare function deactivateUser(ctx: AuthContext, userId: string): Promise<void>;

package/dist/auth/users.js

@@ -0,0 +1,58 @@
+import { randomUUID } from "node:crypto";
+// The user row behind a sign-in. Created the first time someone arrives,
+// refreshed on every visit from what Plaza says now (name, email, avatar), and
+// keyed on the mii id — the one thing about a person that never changes.
+//
+// Which table, and its shape, is the app's (UsersConfig). An app that had
+// people before it had the kit may hold rows with no mii id yet; those are
+// claimed by address on first sign-in rather than duplicated beside a new row.
+export async function upsertMemberFromIdentity(ctx, identity) {
+    const sql = await ctx.getSql();
+    const { users } = ctx;
+    const table = sql(users.table);
+    const avatar = sql(users.avatarColumn);
+    const lastLogin = sql(users.lastLoginColumn);
+    // A NOT NULL address column and a person with none: something unique that
+    // reads as what it is, rather than a refused sign-in.
+    const email = identity.email ?? (users.emailRequired ? `${identity.miiId}@no-email.mii` : null);
+    const [known] = await sql `
+    update ${table} set
+      email = ${email},
+      name = ${identity.name},
+      ${avatar} = ${identity.avatarUrl},
+      ${lastLogin} = now()
+    where mii_id = ${identity.miiId}
+    returning id, status`;
+    if (known !== undefined)
+        return known;
+    if (users.adoptByEmail && identity.email !== null) {
+        const [adopted] = await sql `
+      update ${table} set
+        mii_id = ${identity.miiId},
+        name = ${identity.name},
+        ${avatar} = ${identity.avatarUrl},
+        ${lastLogin} = now()
+      where mii_id is null and lower(email) = lower(${identity.email})
+      returning id, status`;
+        if (adopted !== undefined)
+            return adopted;
+    }
+    const row = {
+        ...users.insertDefaults,
+        ...(users.idFrom === "kit" ? { id: randomUUID() } : {}),
+        mii_id: identity.miiId,
+        email,
+        name: identity.name,
+        [users.avatarColumn]: identity.avatarUrl,
+        [users.lastLoginColumn]: new Date()
+    };
+    const [created] = await sql `
+    insert into ${table} ${sql(row)}
+    returning id, status`;
+    return created;
+}
+/** Deactivate a user: their sessions stop working on the next request. */
+export async function deactivateUser(ctx, userId) {
+    const sql = await ctx.getSql();
+    await sql `update ${sql(ctx.users.table)} set status = 'inactive' where id = ${userId}`;
+}

package/dist/next/index.d.ts

@@ -0,0 +1,17 @@
+/** Plaza origins allowed to frame an org app. Keep in step with the pane. */
+export declare const PLAZA_FRAME_ORIGINS: readonly ["https://plaza.miis.run", "https://miiplaza.vercel.app", "http://localhost:3000", "http://localhost:3111"];
+type Header = {
+    key: string;
+    value: string;
+};
+type HeaderRule = {
+    source: string;
+    headers: Header[];
+    [k: string]: unknown;
+};
+type NextConfigLike = {
+    headers?: () => Promise<HeaderRule[]>;
+    [k: string]: unknown;
+};
+export declare function withMiiPlatform(config?: NextConfigLike): NextConfigLike;
+export {};

package/dist/next/index.js

@@ -0,0 +1,70 @@
+// The Next.js config every mii org app must not diverge from — the framing
+// contract with Plaza's App pane. An app composes its own config through this
+// wrapper; the platform's requirements are force-merged on top so an app cannot
+// accidentally forbid Plaza from embedding it (which shows as a white pane).
+//
+//   // next.config.mjs
+//   import { withMiiPlatform } from "@shubh90/app-runtime/next";
+//   export default withMiiPlatform({ /* the app's own config */ });
+//
+// Newmark SF set `frame-ancestors 'none'` + `X-Frame-Options: DENY` in its own
+// config and white-screened its pane. This makes that impossible: whatever the
+// app sets, the resulting headers frame-allow Plaza and carry no X-Frame-Options.
+/** Plaza origins allowed to frame an org app. Keep in step with the pane. */
+export const PLAZA_FRAME_ORIGINS = [
+    "https://plaza.miis.run",
+    "https://miiplaza.vercel.app",
+    "http://localhost:3000",
+    "http://localhost:3111"
+];
+const FRAME_ANCESTORS = `frame-ancestors 'self' ${PLAZA_FRAME_ORIGINS.join(" ")}`;
+/** Force `frame-ancestors` to allow Plaza in a Content-Security-Policy value. */
+function forceFrameAncestors(csp) {
+    const directives = csp
+        .split(";")
+        .map((d) => d.trim())
+        .filter((d) => d !== "" && !d.toLowerCase().startsWith("frame-ancestors"));
+    directives.push(FRAME_ANCESTORS);
+    return directives.join("; ");
+}
+/** Rewrite one route's headers: fix any CSP's frame-ancestors, drop XFO. */
+function enforce(headers) {
+    let sawCsp = false;
+    const out = [];
+    for (const h of headers) {
+        const key = h.key.toLowerCase();
+        if (key === "x-frame-options")
+            continue; // cannot allowlist; CSP governs
+        if (key === "content-security-policy") {
+            sawCsp = true;
+            out.push({ key: h.key, value: forceFrameAncestors(h.value) });
+            continue;
+        }
+        out.push(h);
+    }
+    if (!sawCsp) {
+        out.push({ key: "Content-Security-Policy", value: FRAME_ANCESTORS });
+    }
+    return out;
+}
+export function withMiiPlatform(config = {}) {
+    const appHeaders = config.headers;
+    return {
+        ...config,
+        async headers() {
+            const rules = appHeaders ? await appHeaders() : [];
+            const enforced = rules.map((rule) => ({
+                ...rule,
+                headers: enforce(rule.headers)
+            }));
+            // Guarantee coverage even if the app declared no header rules at all.
+            if (!enforced.some((r) => r.source === "/:path*")) {
+                enforced.push({
+                    source: "/:path*",
+                    headers: [{ key: "Content-Security-Policy", value: FRAME_ANCESTORS }]
+                });
+            }
+            return enforced;
+        }
+    };
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@shubh90/app-runtime",
+  "version": "0.1.0",
+  "description": "The platform contract every mii org app depends on \u2014 sign-in, and the Next.js config an app must not diverge from. A versioned package, not files copied into each repo.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shubh9/mii.git",
+    "directory": "packages/app-runtime"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js"
+    },
+    "./next": {
+      "types": "./dist/next/index.d.ts",
+      "import": "./dist/next/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --import tsx \"test/**/*.test.ts\"",
+    "check": "npm run typecheck && npm run test"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "postgres": ">=3"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "next": "^15",
+    "postgres": "^3.4.9",
+    "tsx": "^4",
+    "typescript": "^5.6"
+  }
+}