@kedge/server 0.0.0-stage → 0.9.0

package/src/admin-shell.ts

@@ -0,0 +1,72 @@
+// The admin's half of the gate (docs/proposals/p0.9-admin-shell.md §2.4, §4.1,
+// §6.3, §9): the Worker's own origin as an admin origin, the two headers that
+// say which session and which authority answered, and the two handshakes that
+// refuse a stale admin or a stale view before any route runs.
+import { type AccessContext, KedgeError } from "@kedge/core";
+import type { Context } from "hono";
+import type { AuthDeps } from "./types";
+
+/** Header names, one place. */
+export const ADMIN_BUILD_HEADER = "x-kedge-admin-build";
+export const AUTHZ_EXPECT_HEADER = "x-kedge-authz-expect";
+export const SESSION_HEADER = "X-Kedge-Session";
+export const AUTHZ_HEADER = "X-Kedge-Authz";
+
+/**
+ * `ADMIN_ORIGINS` plus the request's own origin (§4.1). That origin serves only
+ * this Worker's API and its own admin assets, so a page on it is the admin: a
+ * fresh store, a preview whose URL is known only after its config is written,
+ * and `kedge dev` all sign in with no configuration.
+ */
+export function adminOriginsFor(c: Context, auth: AuthDeps): readonly string[] {
+  return [...auth.adminOrigins, new URL(c.req.url).origin];
+}
+
+const hex = (b: ArrayBuffer) => [...new Uint8Array(b)].map((x) => x.toString(16).padStart(2, "0")).join("");
+const sha256 = async (text: string) => hex(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+
+/**
+ * What one request was authorized as (§9): the principal, the session's method,
+ * the effective grants with their row scopes, the member's locations, and the
+ * deployment's access contract. A change in any of them changes what an
+ * answer may show, so the admin drops what it rendered under the old one.
+ * The session's id is left out on purpose: a re-sign-in as the same principal
+ * keeps a pending command's view (§6.3).
+ */
+export async function authzFingerprint(ctx: AccessContext, method: string | null, contract: string): Promise<string> {
+  const grants = [...ctx.grants.entries()]
+    .map(([permission, scopes]) => [permission, [...scopes].sort()] as const)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  const principal = "id" in ctx.principal ? `${ctx.principal.kind}:${ctx.principal.id}` : ctx.principal.kind;
+  return sha256(JSON.stringify({ v: 1, principal, method, grants, locations: [...ctx.locations].sort(), contract }));
+}
+
+/**
+ * The build handshake (§2.4): a request naming another admin build is refused
+ * before any route runs, reads included. A Worker with no admin build (no
+ * admin bundled, or a test) refuses every admin-build header, since no build
+ * it could serve matches. Clients that send no header are untouched.
+ */
+export function checkAdminBuild(c: Context, build: string | null): void {
+  const sent = c.req.header(ADMIN_BUILD_HEADER);
+  if (sent === undefined) return;
+  if (build === null || sent !== build)
+    throw new KedgeError("ADMIN_OUTDATED", "The admin was updated; load it again", { build });
+}
+
+/**
+ * The view handshake (§6.3): a mutation made from a view this request no
+ * longer has (another principal, narrowed grants, a deploy that changed the
+ * access contract) is refused before admission or execution.
+ */
+export function checkView(c: Context, fingerprint: string): void {
+  const sent = c.req.header(AUTHZ_EXPECT_HEADER);
+  if (sent !== undefined && sent !== fingerprint)
+    throw new KedgeError("VIEW_CHANGED", "What you may see or do changed since this form loaded; reload it");
+}
+
+/** Names the session and the authority on every staff answer, errors included (§9). */
+export function nameAnswer(c: Context, sessionId: string, fingerprint: string): void {
+  c.header(SESSION_HEADER, sessionId);
+  c.header(AUTHZ_HEADER, fingerprint);
+}