@sigrun/sigrun 0.1.5 → 0.2.0

package/dist/server/login/http.js

@@ -0,0 +1,31 @@
+import { buildSessionCookie, sessionTtlMs } from "../routes/auth.js";
+/** Translate one policy outcome into the browser's redirect/cookie response. */
+export async function sendLoginResolution(outcome, input) {
+    if (outcome.kind === "refused") {
+        if (input.asJson === true)
+            return input.reply.code(403).send({ error: outcome.error });
+        return input.reply.code(403)
+            .header("location", `/login?error=${encodeURIComponent(outcome.error)}`)
+            .send();
+    }
+    if (outcome.kind === "needs_code") {
+        if (input.asJson === true)
+            return input.reply.code(403).send({ error: "invalid_code" });
+        return input.reply.code(403).header("location", "/login?error=invalid_code").send();
+    }
+    if (outcome.kind === "linked") {
+        const returnTo = "/settings?section=accounts";
+        if (input.asJson === true)
+            return input.reply.send({ returnTo });
+        return input.reply.code(302).header("location", returnTo).send();
+    }
+    const session = await input.ctx.opened.identity.tokens.createSession(outcome.user, input.provider, sessionTtlMs(input.ctx));
+    const cookie = buildSessionCookie(session.token, input.request, input.ctx);
+    if (input.asJson === true) {
+        return input.reply.header("set-cookie", cookie).send({ returnTo: input.returnTo });
+    }
+    return input.reply.code(302)
+        .header("location", input.returnTo)
+        .header("set-cookie", cookie)
+        .send();
+}

package/dist/server/login/resolve.js

@@ -0,0 +1,133 @@
+import { AccountLinkConflictError, } from "../../harness/identity/accounts.js";
+import { AdmissionRefusedError, } from "../../harness/identity/users.js";
+import { setupCodeMatches } from "../../harness/identity/setup-code-check.js";
+import { hashToken } from "../../harness/identity/tokens.js";
+import { withClaimLock } from "../auth/claim-lock.js";
+import { assignUsername } from "./usernames.js";
+function allowed(result, policy) {
+    if (policy.allowedGroups !== undefined &&
+        !policy.allowedGroups.some((group) => result.groups?.includes(group) === true))
+        return false;
+    if (policy.allowedDomains !== undefined) {
+        if (result.profile.emailVerified !== true)
+            return false;
+        const email = result.profile.email;
+        const domain = email?.slice(email.lastIndexOf("@") + 1).toLowerCase();
+        if (email === undefined ||
+            email.lastIndexOf("@") <= 0 ||
+            !policy.allowedDomains.some((allowedDomain) => allowedDomain.toLowerCase() === domain))
+            return false;
+    }
+    return true;
+}
+function profileFields(profile) {
+    return {
+        ...(profile.name === undefined ? {} : { name: profile.name }),
+        ...(profile.email === undefined ? {} : { email: profile.email }),
+    };
+}
+/** Resolve one verified external identity without ever inferring an existing-user link. */
+export async function resolveLogin(input, deps) {
+    const { provider, result } = input;
+    try {
+        if (input.linkUser !== undefined) {
+            await deps.accounts.link({
+                provider,
+                subject: result.subject,
+                user: input.linkUser,
+                via: "login",
+            });
+            // A link records identity only. Groups arrive on this account's
+            // next sign-in, never on a session/token-authenticated request.
+            return { kind: "linked", user: input.linkUser };
+        }
+        const existing = deps.accounts.lookup(provider, result.subject);
+        if (existing !== undefined) {
+            if (deps.users.get(existing.user) === undefined) {
+                return { kind: "refused", error: "not_allowed" };
+            }
+            await deps.users.setGroups(existing.user, provider, result.groups ?? []);
+            return { kind: "session", user: existing.user };
+        }
+        const setupResolution = await withClaimLock(async () => {
+            const validSetupCode = input.code !== undefined && setupCodeMatches(input.code, deps.setupCode());
+            if (deps.users.isClaimed()) {
+                // A setup code never creates a user on a claimed server. It may
+                // only finish the exact claim whose subject/user/code were recorded.
+                if (!validSetupCode)
+                    return undefined;
+                const claim = deps.setupClaims.matches(provider, result.subject, input.code);
+                if (claim === undefined || deps.users.get(claim.user) === undefined) {
+                    return { kind: "refused", error: "not_allowed" };
+                }
+                await deps.accounts.link({ provider, subject: result.subject, user: claim.user, via: "login" });
+                await deps.users.setGroups(claim.user, provider, result.groups ?? []);
+                await deps.clearSetupCode();
+                await deps.setupClaims.clear();
+                return { kind: "session", user: claim.user };
+            }
+            if (!validSetupCode)
+                return { kind: "needs_code", reason: "setup" };
+            const claim = deps.setupClaims.matches(provider, result.subject, input.code);
+            const user = claim?.user ?? assignUsername(result.profile, result.subject, (name) => deps.users.get(name) !== undefined);
+            // Persist the recovery breadcrumb before creating the user. On a
+            // retry, only this exact subject may finish the claim; if the user
+            // write did not happen, it is retried under the recorded name.
+            await deps.setupClaims.record({
+                user,
+                provider,
+                subject: result.subject,
+                codeSha256: hashToken(input.code),
+            });
+            const record = deps.users.get(user) ?? await deps.users.add({
+                user,
+                ...profileFields(result.profile),
+                admin: true,
+                source: "login",
+            });
+            await deps.accounts.link({ provider, subject: result.subject, user, via: "login" });
+            await deps.users.setGroups(user, provider, result.groups ?? []);
+            await deps.clearSetupCode();
+            await deps.setupClaims.clear();
+            return { kind: "session", user: record.user };
+        });
+        if (setupResolution !== undefined)
+            return setupResolution;
+        if (deps.policy.autoProvision === true && !allowed(result, deps.policy)) {
+            return { kind: "refused", error: "not_allowed" };
+        }
+        if (deps.policy.autoProvision !== true && input.code === undefined) {
+            return { kind: "needs_code", reason: "invite" };
+        }
+        // Admission is checked before redemption so an M1 refusal burns no invite.
+        deps.users.checkAdmission();
+        const user = assignUsername(result.profile, result.subject, (name) => deps.users.get(name) !== undefined);
+        const grant = deps.policy.autoProvision === true
+            ? { admin: false }
+            : await deps.invites.redeem(input.code, user);
+        if (grant === undefined)
+            return { kind: "refused", error: "not_allowed" };
+        const record = await deps.users.add({
+            user,
+            ...profileFields(result.profile),
+            admin: grant.admin,
+            source: "login",
+        });
+        await deps.accounts.link({ provider, subject: result.subject, user, via: "login" });
+        await deps.users.setGroups(user, provider, result.groups ?? []);
+        return { kind: "session", user: record.user };
+    }
+    catch (error) {
+        if (error instanceof AccountLinkConflictError || (error instanceof Error && error.message.startsWith("account_link_conflict:")))
+            return { kind: "refused", error: "account_link_conflict" };
+        if (error instanceof AdmissionRefusedError)
+            return { kind: "refused", error: error.code };
+        if (error instanceof Error && error.message.startsWith("isolation_required:")) {
+            return { kind: "refused", error: "isolation_required" };
+        }
+        if (error instanceof Error && error.message.startsWith("auth_required:")) {
+            return { kind: "refused", error: "auth_required" };
+        }
+        throw error;
+    }
+}

package/dist/server/login/setup-claim.js

@@ -0,0 +1,55 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { hashToken } from "../../harness/identity/tokens.js";
+import { writeJson } from "../../harness/identity/json-store.js";
+/**
+ * A durable breadcrumb for the one setup-code-paid claim. It lets a retry
+ * finish a crashed link without ever inferring ownership from a username.
+ */
+export class SetupClaimStore {
+    #path;
+    #memory;
+    constructor(cacheDir) {
+        this.#path = cacheDir === undefined ? undefined : join(cacheDir, "login-setup-claim.json");
+    }
+    read() {
+        if (this.#path === undefined)
+            return this.#memory;
+        try {
+            const value = JSON.parse(readFileSync(this.#path, "utf8"));
+            if (typeof value !== "object" || value === null)
+                throw new Error("not an object");
+            const record = value;
+            if (typeof record.user !== "string" || typeof record.provider !== "string" ||
+                typeof record.subject !== "string" || typeof record.codeSha256 !== "string")
+                throw new Error("invalid fields");
+            return record;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw new Error(`sigrun: malformed login setup claim in ${this.#path}`, { cause: error });
+        }
+    }
+    async record(claim) {
+        if (this.#path === undefined) {
+            this.#memory = claim;
+            return;
+        }
+        await writeJson(this.#path, claim);
+    }
+    matches(provider, subject, code) {
+        const claim = this.read();
+        return claim?.provider === provider && claim.subject === subject && claim.codeSha256 === hashToken(code)
+            ? claim
+            : undefined;
+    }
+    async clear() {
+        if (this.#path === undefined) {
+            this.#memory = undefined;
+            return;
+        }
+        const { rm } = await import("node:fs/promises");
+        await rm(this.#path, { force: true });
+    }
+}

package/dist/server/login/usernames.js

@@ -0,0 +1,15 @@
+/** Assign a new directory username; this never selects an existing user. */
+export function assignUsername(profile, subject, taken) {
+    const candidate = profile.username ?? profile.email?.split("@", 1)[0] ?? subject;
+    const base = candidate
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]/g, "-")
+        .replace(/^[^a-z0-9]+/, "") || "user";
+    if (!taken(base))
+        return base;
+    for (let suffix = 2;; suffix++) {
+        const candidateWithSuffix = `${base}-${suffix}`;
+        if (!taken(candidateWithSuffix))
+            return candidateWithSuffix;
+    }
+}

package/dist/server/ownership.js

@@ -13,6 +13,8 @@
  * receive, while the registry is server-instance state.
  */
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { AgentDoc } from "@earendil-works/pi-durable";
+import { isAbsolute, join, resolve } from "node:path";
 import { SCAN_PAGE_SIZE } from "./helpers.js";
 import { SessionMetaDoc } from "./session-meta.js";
 /** The per-server participant lists (registration order = run order). */
@@ -46,6 +48,8 @@ export async function transferOwnership(ctx, from, to) {
 export function registerCoreOwnershipParticipant(ctx) {
     registerOwnershipParticipant(ctx, async (from, to) => {
         const { opened } = ctx;
+        const fromWorkspace = opened.identity.users.get(from)?.workspace ??
+            join(ctx.managedPaths.userAreas(from), "workspace");
         let cursor;
         do {
             const page = await opened.storage.scanConversations({ order: "ascending" }, SCAN_PAGE_SIZE, cursor, BACKGROUND_CONTEXT);
@@ -59,6 +63,15 @@ export function registerCoreOwnershipParticipant(ctx) {
                 await conversation.commit(async (tx) => {
                     const draft = await tx.doc(SessionMetaDoc, conversation.id);
                     draft.owner = to;
+                    const agent = await tx.doc(AgentDoc, conversation.id);
+                    // Pin the old owner's resolution before ownership changes: a
+                    // relative cwd must not retarget into the new owner's workspace.
+                    if (agent.cwd === undefined)
+                        agent.cwd = fromWorkspace;
+                    else if (!isAbsolute(agent.cwd)) {
+                        agent.cwd = resolve(fromWorkspace, agent.cwd);
+                    }
+                    await opened.rewriteUserSelection(tx, conversation.id, from, to);
                 }, BACKGROUND_CONTEXT);
             }
             cursor = page.next;

package/dist/server/routes/admin.js

@@ -0,0 +1,58 @@
+/**
+ * Admin routes (UI-blocks U4 Task 2, spec §13.3):
+ * `POST /v1/admin/restart` — the graceful in-place restart.
+ *
+ * The route exists ONLY under the supervised posture: `server.supervised`
+ * (env `SIGRUN_SUPERVISED`, config resolution) promises that something
+ * restarts the process after an intentional `exit 0` — the Helm chart
+ * and docker compose set it (both restart the container); the
+ * Dockerfile deliberately does NOT, so a bare `docker run` reports
+ * `not_supervised` rather than dying permanently.
+ *
+ * Semantics: admin-only (403 before any body read, like PATCH
+ * /v1/settings); unsupervised → 409 `{error: "not_supervised"}` and
+ * NOTHING runs; supervised admin → 202 `{restarting: true}` and the
+ * restart callback is scheduled on the NEXT tick (`setImmediate`) so
+ * the response always flushes before the drain begins. The callback
+ * (ServerContext.requestRestart, the serve composition's
+ * graceful-shutdown + `process.exit(0)`) owns the exit — the route
+ * never calls exit itself.
+ *
+ * Durability (Review Focus 4): the restart rides the SAME ordered
+ * shutdown as the SIGTERM path — the event bus drains pending settles
+ * and the harness close seals storage, so a run in flight at restart
+ * has its submission durable before exit; pi-durable resumes it after
+ * the supervisor brings the process back.
+ */
+/** Register the `/v1/admin` routes. */
+export function registerAdminRoutes(app, ctx) {
+    app.post("/v1/admin/restart", async (request, reply) => {
+        // Admin-only: a restart is a control-plane action (it kills every
+        // in-flight connection, including other users' streams) — the
+        // gate runs before the supervised check so a non-admin learns
+        // nothing about the deploy's supervision posture.
+        if (!request.principal.admin) {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        if (!ctx.config.supervised) {
+            return await reply.code(409).send({ error: "not_supervised" });
+        }
+        // Deferred past the reply: the 202 must reach the client before
+        // the drain closes its connection. A supervisor is expected, so a
+        // missing callback (a hand-built server in a test that forgot the
+        // seam) is a loud boot-composition error, not a silent no-op.
+        if (ctx.requestRestart === undefined) {
+            throw new Error("admin restart: supervised but no restart callback wired (serve composition error)");
+        }
+        const restart = ctx.requestRestart;
+        setImmediate(() => {
+            void Promise.resolve(restart()).catch((error) => {
+                // The shutdown path is already committed at this point —
+                // nothing to roll back to; log loud and let the exit/error
+                // surface in the deploy's logs.
+                console.error("sigrun: restart shutdown failed:", error);
+            });
+        });
+        return await reply.code(202).send({ restarting: true });
+    });
+}

package/dist/server/routes/auth.js

@@ -19,9 +19,18 @@
  * never a delegated act); listing serves the caller's tokens, with
  * `?user=` the admin-only window into another's; revocation deletes the
  * caller's own tokens, or any for an admin.
+ *
+ * Account links (multi-user M3a, spec §11.3) mirror the token routes
+ * exactly in who-may-see-what: `GET /v1/auth/accounts` lists the
+ * caller's own links (`?user=` is the admin-only window into another's),
+ * and `DELETE /v1/auth/accounts` removes one — the caller's own, or any
+ * for an admin. Both take QUERY parameters rather than path segments:
+ * provider ids contain `:` and subjects may contain `/`, `+`, or `@`.
  */
 import { ipAllowed } from "../auth/ip.js";
+import { sessionCookieOf } from "../auth/pipeline.js";
 import { LoginLimiter } from "../auth/login-limiter.js";
+import { accountLinkWire } from "../views.js";
 /** The session cookie name (spec §5.4). */
 export const SESSION_COOKIE = "sigrun_session";
 /** The failed-login delay (ms), per the brief. */
@@ -37,9 +46,16 @@ export function buildSessionCookie(token, request, ctx) {
     const forwarded = request.headers["x-forwarded-proto"];
     const forwardedProto = Array.isArray(forwarded) ? forwarded[0] : forwarded;
     const secure = request.protocol === "https" || (trusted && forwardedProto === "https");
-    return (`${SESSION_COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/` +
+    const maxAge = sessionTtlMs(ctx) / 1_000;
+    return (`${SESSION_COOKIE}=${token}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${maxAge}` +
         (secure ? "; Secure" : ""));
 }
+/** The live session TTL consumed by the login flow (days → milliseconds). */
+export function sessionTtlMs(ctx) {
+    const days = ctx.opened.settings.read().server?.auth?.sessionDays ??
+        ctx.config.auth.sessionDays;
+    return days * 86_400_000;
+}
 /** The wire form of one token record — never the digest. */
 function tokenWire(record) {
     return {
@@ -47,6 +63,8 @@ function tokenWire(record) {
         name: record.name,
         user: record.user,
         createdAt: record.createdAt,
+        ...(record.kind === undefined ? {} : { kind: record.kind }),
+        ...(record.expiresAt === undefined ? {} : { expiresAt: record.expiresAt }),
     };
 }
 /** Register the auth routes: login, logout, whoami, and token management. */
@@ -81,7 +99,14 @@ export function registerAuthRoutes(app, ctx) {
             .header("set-cookie", buildSessionCookie(token, request, ctx))
             .send({ user: user.user });
     });
-    app.post("/v1/auth/logout", async (_request, reply) => {
+    app.post("/v1/auth/logout", async (request, reply) => {
+        const presented = sessionCookieOf(request);
+        const record = presented
+            ? ctx.opened.identity.tokens.verify(presented)
+            : undefined;
+        if (record?.kind === "session") {
+            await ctx.opened.identity.tokens.revoke(record.id);
+        }
         return await reply
             .code(204)
             .header("set-cookie", `${SESSION_COOKIE}=; HttpOnly; SameSite=Strict; Path=/; Max-Age=0`)
@@ -89,13 +114,19 @@ export function registerAuthRoutes(app, ctx) {
     });
     app.get("/v1/auth/whoami", async (request) => {
         const principal = request.principal;
+        const record = principal.user === undefined
+            ? undefined
+            : ctx.opened.identity.users.get(principal.user);
         return {
             ...(principal.user === undefined ? {} : { user: principal.user }),
             ...(principal.name === undefined ? {} : { name: principal.name }),
             ...(principal.email === undefined ? {} : { email: principal.email }),
+            ...(record?.workspace === undefined ? {} : { workspace: record.workspace }),
+            ...(record?.grants === undefined ? {} : { grants: record.grants }),
             admin: principal.admin,
             service: principal.service,
             method: principal.method,
+            ...(principal.provider === undefined ? {} : { provider: principal.provider }),
         };
     });
     // ─── Token management (Task 4) ─────────────────────────────────────
@@ -169,4 +200,59 @@ export function registerAuthRoutes(app, ctx) {
         await ctx.opened.identity.tokens.revoke(id);
         return await reply.code(204).send();
     });
+    // ─── Account links (multi-user M3a, spec §11.3) ────────────────────
+    app.get("/v1/auth/accounts", async (request, reply) => {
+        const principal = request.principal;
+        const query = request.query;
+        // `?user=` is the admin-only window into another's links; naming
+        // oneself is the same payload as no query (the identity is theirs
+        // either way) and is allowed for the same reason the token list
+        // allows it.
+        if (query.user !== undefined) {
+            if (!principal.admin && query.user !== principal.user) {
+                return await reply.code(403).send({ error: "forbidden" });
+            }
+            const response = {
+                accounts: ctx.opened.identity.accounts
+                    .listForUser(query.user)
+                    .map(accountLinkWire),
+            };
+            return response;
+        }
+        // The caller's own links — a principal with no directory user (the
+        // naive single-operator superuser, a userless service principal)
+        // gets the whole store, which for that posture IS the operator's own
+        // (the same rule the token list applies).
+        const response = {
+            accounts: principal.user === undefined
+                ? ctx.opened.identity.accounts.list().map(accountLinkWire)
+                : ctx.opened.identity.accounts
+                    .listForUser(principal.user)
+                    .map(accountLinkWire),
+        };
+        return response;
+    });
+    app.delete("/v1/auth/accounts", async (request, reply) => {
+        const principal = request.principal;
+        const query = request.query;
+        if (query.provider === undefined ||
+            query.provider === "" ||
+            query.subject === undefined ||
+            query.subject === "") {
+            return await reply.code(400).send({ error: "invalid_query" });
+        }
+        // The lookup, the ownership check, and the removal happen INSIDE one
+        // serialized mutation: reading the link here and removing it later
+        // would leave a window where the subject is unlinked and re-linked
+        // to a different user, and this request would delete the NEW
+        // holder's link on the strength of a stale check.
+        const outcome = await ctx.opened.identity.accounts.unlinkAuthorized(query.provider, query.subject, { user: principal.user, admin: principal.admin });
+        if (outcome === "absent") {
+            return await reply.code(404).send({ error: "unknown_account" });
+        }
+        if (outcome === "forbidden") {
+            return await reply.code(403).send({ error: "forbidden" });
+        }
+        return await reply.code(204).send();
+    });
 }

package/dist/server/routes/conversations.js

@@ -7,7 +7,7 @@
  * list, import) take no pre-handler.
  */
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
-import { isSuperuser } from "../auth/principal.js";
+import { accessPrincipalOf } from "../auth/access-principal.js";
 import { ConversationOpError, createConversationOp, forkOp, listConversationsOp, patchMetaOp, readMetaOp, } from "../conversation-ops.js";
 import { loadConversation } from "../conversation-handler.js";
 import { ID_PARAMS_SCHEMA, readView, stampSessionOwner, storeAgentChange, } from "../helpers.js";
@@ -70,10 +70,7 @@ export function registerConversationRoutes(app, ctx) {
                 : { archivedOnly: query.archived === "true" }),
             ...(query.mine === "true" ? { mine: true } : {}),
         };
-        const conversations = await listConversationsOp(ctx, {
-            user: request.principal.user,
-            superuser: isSuperuser(request.principal),
-        }, filters);
+        const conversations = await listConversationsOp(ctx, accessPrincipalOf(request.principal, opened.identity.users), filters);
         return { conversations };
     });
     app.get("/v1/conversations/:id", { schema: { params: ID_PARAMS_SCHEMA }, preHandler: loadConversation(ctx) }, async (request) => {
@@ -234,7 +231,7 @@ export function registerConversationRoutes(app, ctx) {
         }, BACKGROUND_CONTEXT);
         // The imported conversation is the IMPORTER's, not the source's
         // (the JSONL never carries meta — the stamp is the only owner).
-        await stampSessionOwner(conversation, request.principal.user);
+        await stampSessionOwner(conversation, request.principal.user, opened);
         const view = await readView(conversation);
         return await reply.code(201).send({ id: conversation.id, view });
     });

package/dist/server/routes/events.js

@@ -31,14 +31,15 @@
 import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
 import { randomUUID } from "node:crypto";
 import { accessOf } from "@sigrun/shared/access";
+import { accessPrincipalOf } from "../auth/access-principal.js";
 import { SessionMetaDoc } from "../session-meta.js";
 /** The heartbeat cadence (the /stream pattern: proxy idle-timeout survival). */
 const HEARTBEAT_MS = 15_000;
 /** Register the global events stream route. */
 export function registerEventRoutes(app, ctx) {
     app.get("/v1/events", async (request, reply) => {
-        const principal = request.principal;
         const { opened } = ctx;
+        const { principal } = request;
         reply.hijack();
         const raw = reply.raw;
         raw.writeHead(200, {
@@ -84,6 +85,9 @@ export function registerEventRoutes(app, ctx) {
          * principal-facing).
          */
         const visible = async (event) => {
+            // Like SessionMeta, stored groups are current PER EVENT: group
+            // changes affect the next event on an existing connection.
+            const accessPrincipal = accessPrincipalOf(principal, opened.identity.users);
             switch (event.type) {
                 // Conversation-scoped: SessionMeta access, re-snapshotted per
                 // event (share → the NEXT event arrives; un-share withholds the
@@ -103,7 +107,7 @@ export function registerEventRoutes(app, ctx) {
                         console.error("events route: SessionMeta snapshot failed:", error);
                         return undefined; // a raced read withholds that one event
                     }
-                    return accessOf(principal, meta ?? {}) !== "none" ? event : undefined;
+                    return accessOf(accessPrincipal, meta ?? {}) !== "none" ? event : undefined;
                 }
                 // Broadcast: every authenticated principal.
                 case "providers.changed":
@@ -112,7 +116,7 @@ export function registerEventRoutes(app, ctx) {
                 // carries the caller's access (the wire adds what the hub's
                 // access-neutral copy omits).
                 case "job.changed": {
-                    const access = accessOf(principal, {
+                    const access = accessOf(accessPrincipal, {
                         ...(event.job.owner === undefined
                             ? {}
                             : { owner: event.job.owner }),
@@ -129,6 +133,12 @@ export function registerEventRoutes(app, ctx) {
                 // principal-facing wire event.
                 case "taskSettled":
                     return undefined;
+                // UI-blocks U4 (spec §13.2): settings changes are OPERATOR
+                // surface — delivered to ADMINS only, both scopes (a
+                // server-scope PATCH and an extension's settings PUT alike;
+                // the admin gate is the same one the writes carry).
+                case "settings.changed":
+                    return request.principal.admin ? event : undefined;
                 // UI-blocks U3 Task 4 (spec §7.3): delivered to a watching
                 // stream ONLY. The hub copy is the service's internal event
                 // (SurfaceChangedInternal) which carries the resolved stream
@@ -137,6 +147,21 @@ export function registerEventRoutes(app, ctx) {
                 // The DELIVERED frame is the wire shape (the internal field
                 // stripped — the stream list is routing metadata, never wire).
                 case "surface.changed": {
+                    // The CHAT shape (U5 Task 2, spec §8.2): conversation-scoped —
+                    // the event names its (conversationId, entryId) directly, so
+                    // visibility is the conversation's own (SessionMeta
+                    // re-snapshotted per event; hidden conversations see nothing).
+                    if ("conversationId" in event) {
+                        let meta;
+                        try {
+                            meta = await opened.harness.snapshot(SessionMetaDoc, event.conversationId, BACKGROUND_CONTEXT);
+                        }
+                        catch (error) {
+                            console.error("events route: SessionMeta snapshot failed:", error);
+                            return undefined;
+                        }
+                        return accessOf(principal, meta ?? {}) !== "none" ? event : undefined;
+                    }
                     // SAFETY: the hub carries the service's internal event (the
                     // wire shape plus the publish-time stream list); every
                     // surface.changed the hub sees comes from bumpRev, which