nixamp 0.28.38 → 0.28.41

package/src/nixamp-link.ts

@@ -0,0 +1,265 @@
+/**
+ * A nixamp account, connected to an account here.
+ *
+ * backtoschool.help runs on the nixamp codebase, and for a while its sign-in
+ * dialog said so: "your BackToSchool identity is your NixAmp account". That
+ * made a password manager file the nixamp password under the school's
+ * address, and it made nixamp a thing every teacher had to have. Neither is
+ * wanted. A BackToSchool account is a BackToSchool account; nixamp is the
+ * broadcast backend a host may plug in, and plugging it in is a choice.
+ *
+ * So the school is an OAuth 2.1 client of nixamp.com, the way bittorrented
+ * is: PKCE, a consent page on nixamp.com, a refresh token kept here against
+ * the school account, and a grant the person can withdraw from either side.
+ * What the connection buys is the list of the servers they run on nixamp and
+ * what is live on them, so "go live" is a pick from a list rather than a
+ * link pasted from a terminal.
+ *
+ * The client half of OAuth is behind an interface, because the server on the
+ * other end is this same program in production and a stub in a test.
+ */
+import { randomBytes } from "node:crypto";
+import type { Queryable } from "./follows.ts";
+import { challengeFor } from "./oauth-server.ts";
+import type { LinkView } from "./nixamp-link-types.ts";
+export type { LinkView } from "./nixamp-link-types.ts";
+
+const TABLE = "nixamp_links";
+
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS ${TABLE} (
+    user_id           TEXT PRIMARY KEY,
+    nixamp_user_id    TEXT NOT NULL,
+    handle            TEXT NOT NULL DEFAULT '',
+    scope             TEXT NOT NULL DEFAULT '',
+    access_token      TEXT NOT NULL DEFAULT '',
+    access_expires_at TIMESTAMPTZ,
+    refresh_token     TEXT NOT NULL DEFAULT '',
+    created_at        TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at        TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  );
+`;
+
+/** What the school asks nixamp for: who you are, your servers, and to keep it. */
+export const LINK_SCOPE = "profile streams offline_access";
+
+/** How long before an access token's end it is treated as spent. */
+const EARLY_MS = 60_000;
+
+export interface TokenGrant {
+  access_token: string;
+  refresh_token?: string;
+  expires_in?: number;
+  scope?: string;
+}
+
+export interface WhoAmI {
+  sub: string;
+  handle?: string;
+}
+
+/** The client side of OAuth 2.1, against the issuer, however it is reached. */
+export interface OAuthExchange {
+  authorizeUrl(query: Record<string, string>): string;
+  /** The token endpoint. Rejects with an Error whose message is fit to show. */
+  token(form: URLSearchParams): Promise<TokenGrant>;
+  userinfo(accessToken: string): Promise<WhoAmI>;
+  revoke(token: string): Promise<void>;
+}
+
+export const NOT_CONNECTED: LinkView = { connected: false, handle: "", nixampUserId: "", scope: "", since: null };
+
+/** The real thing: nixamp.com over HTTP. */
+export function nixampExchange(issuer: string, clientId: string, fetcher: typeof fetch = fetch): OAuthExchange {
+  const base = issuer.replace(/\/+$/, "");
+  async function post(path: string, form: URLSearchParams, accept: "json" | "none"): Promise<Record<string, unknown>> {
+    let response: Response;
+    try {
+      response = await fetcher(`${base}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+        body: form.toString(),
+        signal: AbortSignal.timeout(10_000),
+      });
+    } catch {
+      throw new Error("nixamp.com could not be reached");
+    }
+    const body = (await response.json().catch(() => ({}))) as Record<string, unknown>;
+    if (!response.ok && accept === "json") {
+      const description = typeof body["error_description"] === "string" ? body["error_description"] : typeof body["error"] === "string" ? body["error"] : `nixamp.com answered ${response.status}`;
+      throw new Error(description);
+    }
+    return body;
+  }
+  return {
+    authorizeUrl(query) {
+      const url = new URL(`${base}/api/v1/oauth/authorize`);
+      for (const [key, value] of Object.entries(query)) url.searchParams.set(key, value);
+      return url.href;
+    },
+    async token(form) {
+      form.set("client_id", clientId);
+      const body = await post("/api/v1/oauth/token", form, "json");
+      if (typeof body["access_token"] !== "string" || body["access_token"] === "") throw new Error("nixamp.com sent no token");
+      return body as unknown as TokenGrant;
+    },
+    async userinfo(accessToken) {
+      let response: Response;
+      try {
+        response = await fetcher(`${base}/api/v1/oauth/userinfo`, {
+          headers: { authorization: `Bearer ${accessToken}`, accept: "application/json" },
+          signal: AbortSignal.timeout(10_000),
+        });
+      } catch {
+        throw new Error("nixamp.com could not be reached");
+      }
+      if (!response.ok) throw new Error("nixamp.com did not say whose token that is");
+      const body = (await response.json().catch(() => ({}))) as Record<string, unknown>;
+      if (typeof body["sub"] !== "string" || body["sub"] === "") throw new Error("nixamp.com did not say whose token that is");
+      return { sub: body["sub"], ...(typeof body["handle"] === "string" ? { handle: body["handle"] } : {}) };
+    },
+    async revoke(token) {
+      const form = new URLSearchParams({ token, client_id: clientId });
+      await post("/api/v1/oauth/revoke", form, "none").catch(() => undefined);
+    },
+  };
+}
+
+function asTime(value: unknown): number | null {
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === "string") {
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? null : at;
+  }
+  return null;
+}
+
+function view(row: Record<string, unknown> | undefined): LinkView {
+  if (!row) return { ...NOT_CONNECTED };
+  return {
+    connected: true,
+    handle: String(row["handle"] ?? ""),
+    nixampUserId: String(row["nixamp_user_id"] ?? ""),
+    scope: String(row["scope"] ?? ""),
+    since: asTime(row["created_at"]),
+  };
+}
+
+export class NixampLinks {
+  private ready: Promise<void> | null = null;
+
+  constructor(
+    private readonly db: Queryable,
+    private readonly exchange: OAuthExchange,
+    private readonly clientId: string,
+    private readonly now: () => number = () => Date.now(),
+    /** How nixamp.com and the servers it lists are reached, for what the tokens are used on. */
+    readonly fetcher: typeof fetch = fetch,
+  ) {}
+
+  private async ensure(): Promise<void> {
+    this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+    await this.ready;
+  }
+
+  /**
+   * The first leg: where to send the browser, and the two secrets the
+   * callback must bring back. The state is the CSRF check, the verifier is
+   * PKCE; both live in a short cookie on the school's origin, never here.
+   */
+  begin(redirectUri: string): { url: string; state: string; verifier: string } {
+    const state = randomBytes(24).toString("base64url");
+    const verifier = randomBytes(48).toString("base64url");
+    const url = this.exchange.authorizeUrl({
+      response_type: "code",
+      client_id: this.clientId,
+      redirect_uri: redirectUri,
+      scope: LINK_SCOPE,
+      state,
+      code_challenge: challengeFor(verifier),
+      code_challenge_method: "S256",
+    });
+    return { url, state, verifier };
+  }
+
+  /** The second leg: the code becomes tokens, the tokens say whose, and that is kept. */
+  async finish(userId: string, leg: { code: string; verifier: string; redirectUri: string }): Promise<LinkView> {
+    const grant = await this.exchange.token(new URLSearchParams({
+      grant_type: "authorization_code",
+      code: leg.code,
+      code_verifier: leg.verifier,
+      redirect_uri: leg.redirectUri,
+    }));
+    const who = await this.exchange.userinfo(grant.access_token);
+    await this.ensure();
+    await this.db.query(
+      `INSERT INTO ${TABLE} (user_id, nixamp_user_id, handle, scope, access_token, access_expires_at, refresh_token)
+       VALUES ($1, $2, $3, $4, $5, $6, $7)
+       ON CONFLICT (user_id) DO UPDATE SET nixamp_user_id = EXCLUDED.nixamp_user_id, handle = EXCLUDED.handle,
+         scope = EXCLUDED.scope, access_token = EXCLUDED.access_token, access_expires_at = EXCLUDED.access_expires_at,
+         refresh_token = EXCLUDED.refresh_token, updated_at = NOW()`,
+      [userId, who.sub, who.handle ?? "", grant.scope ?? LINK_SCOPE, grant.access_token, this.expiry(grant), grant.refresh_token ?? ""],
+    );
+    return this.of(userId);
+  }
+
+  private expiry(grant: TokenGrant): Date {
+    const seconds = typeof grant.expires_in === "number" && grant.expires_in > 0 ? grant.expires_in : 3600;
+    return new Date(this.now() + seconds * 1000);
+  }
+
+  async of(userId: string): Promise<LinkView> {
+    await this.ensure();
+    const { rows } = await this.db.query(
+      `SELECT nixamp_user_id, handle, scope, created_at FROM ${TABLE} WHERE user_id = $1`,
+      [userId],
+    );
+    return view(rows[0]);
+  }
+
+  /**
+   * A token good for a call right now, refreshed when the one kept is about
+   * to end. "" when there is no connection, or the refresh was refused --
+   * which is what a grant withdrawn on nixamp.com looks like from here, and
+   * the row is dropped so the settings page says so too.
+   */
+  async accessToken(userId: string): Promise<string> {
+    await this.ensure();
+    const { rows } = await this.db.query(
+      `SELECT access_token, access_expires_at, refresh_token FROM ${TABLE} WHERE user_id = $1`,
+      [userId],
+    );
+    const row = rows[0];
+    if (!row) return "";
+    const access = String(row["access_token"] ?? "");
+    const until = asTime(row["access_expires_at"]);
+    if (access !== "" && until !== null && until - this.now() > EARLY_MS) return access;
+    const refresh = String(row["refresh_token"] ?? "");
+    if (refresh === "") return "";
+    let grant: TokenGrant;
+    try {
+      grant = await this.exchange.token(new URLSearchParams({ grant_type: "refresh_token", refresh_token: refresh }));
+    } catch {
+      await this.db.query(`DELETE FROM ${TABLE} WHERE user_id = $1`, [userId]);
+      return "";
+    }
+    await this.db.query(
+      `UPDATE ${TABLE} SET access_token = $2, access_expires_at = $3, refresh_token = $4, updated_at = NOW() WHERE user_id = $1`,
+      [userId, grant.access_token, this.expiry(grant), grant.refresh_token ?? refresh],
+    );
+    return grant.access_token;
+  }
+
+  /** Withdraw the grant on nixamp.com and forget it here. True when there was one. */
+  async disconnect(userId: string): Promise<boolean> {
+    await this.ensure();
+    const { rows } = await this.db.query(`SELECT refresh_token, access_token FROM ${TABLE} WHERE user_id = $1`, [userId]);
+    const row = rows[0];
+    if (!row) return false;
+    const refresh = String(row["refresh_token"] ?? "");
+    const access = String(row["access_token"] ?? "");
+    await this.exchange.revoke(refresh !== "" ? refresh : access);
+    await this.db.query(`DELETE FROM ${TABLE} WHERE user_id = $1`, [userId]);
+    return true;
+  }
+}

package/src/notify.ts

@@ -1,3 +1,4 @@
+import { sendPush } from "@profullstack/notifications/server";
 import { mailSender, type BrandedMailSender } from "./mail-sender.ts";
 
 /**
@@ -168,53 +169,37 @@ function escapeHtml(value: string): string {
 /**
  * Web push, to a browser, a desktop app or an installed PWA.
  *
- * The library is imported lazily because it is only needed on the instance
- * that has VAPID keys -- which is nixamp.com and nowhere else. A laptop
- * running `nixamp serve` should not pay to load it.
+ * Sent with @profullstack/notifications, which does VAPID and the payload
+ * encryption with node:crypto and nothing else, so there is no library to load
+ * lazily on the one instance (nixamp.com) that has keys. The keys are the same
+ * base64url pair web-push used, so nothing had to be regenerated.
  *
  * 404 and 410 mean the vendor has retired the subscription. That is not a
  * failure to retry; it is a row to delete.
  */
 export function webPush(
-  { publicKey, privateKey, subject, onEvent }: {
+  { publicKey, privateKey, subject, onEvent, fetch }: {
     publicKey: string;
     privateKey: string;
     /** A mailto: or https: URL identifying us to the push service. */
     subject: string;
     onEvent?: (message: string) => void;
+    fetch?: typeof globalThis.fetch;
   },
 ): (target: PushTarget, note: Notification) => Promise<PushResult> {
-  let library: Promise<{ sendNotification: Function; setVapidDetails: Function }> | null = null;
-
-  const load = async () => {
-    library ??= import("web-push").then((mod) => {
-      const wp = ((mod as Record<string, unknown>)["default"] ?? mod) as {
-        sendNotification: Function;
-        setVapidDetails: Function;
-      };
-      wp.setVapidDetails(subject, publicKey, privateKey);
-      return wp;
-    });
-    return library;
-  };
-
+  const keys = { publicKey, privateKey };
   return async (target, note) => {
-    try {
-      const wp = await load();
-      await wp.sendNotification(
-        { endpoint: target.endpoint, keys: { p256dh: target.p256dh, auth: target.auth } },
-        JSON.stringify({ title: note.title, body: note.body, url: note.url }),
-        { TTL: 60 * 30 },
-      );
-      return "sent";
-    } catch (error) {
-      const status = (error as { statusCode?: number }).statusCode;
-      if (status === 404 || status === 410) {
-        onEvent?.(`  push endpoint retired by the vendor, dropping it`);
-        return "gone";
-      }
-      onEvent?.(`  push failed: ${status ?? (error as Error).message}`);
-      return "failed";
+    const result = await sendPush(
+      { endpoint: target.endpoint, keys: { p256dh: target.p256dh, auth: target.auth } },
+      { title: note.title, body: note.body, url: note.url },
+      { keys, subject, ttl: 60 * 30, ...(fetch ? { fetch } : {}) },
+    );
+    if (result.sent) return "sent";
+    if (result.gone) {
+      onEvent?.(`  push endpoint retired by the vendor, dropping it`);
+      return "gone";
     }
+    onEvent?.(`  push failed: ${result.status ?? result.error}`);
+    return "failed";
   };
 }

package/src/oauth-api.ts

@@ -13,7 +13,7 @@
  *
  *   POST /api/v1/watch-parties               bridge one, idempotently
  *   GET  /api/v1/watch-parties               the ones you could join
- *   GET  /api/v1/watch-parties/<code>        one, with where playback is
+ *   GET  /api/v1/watch-parties/<code>        one, with where playback is (open: the code is the invitation)
  *   POST /api/v1/watch-parties/<code>/playback  the host moving everybody
  *   POST /api/v1/watch-parties/<code>/end       the host ending it
  *
@@ -189,12 +189,12 @@ async function callerFor(
   return account ? { account, clientId: "", scope: SCOPE_NAMES } : null;
 }
 
-function partyBody(parties: WatchParties, view: PartyView, caller: Caller): Record<string, unknown> {
+function partyBody(parties: WatchParties, view: PartyView, caller: Caller | null): Record<string, unknown> {
   return {
     party: { ...view.party, positionNow: parties.positionNow(view.party) },
     event: view.event,
     links: parties.links(view.party),
-    host: view.event.ownerId === caller.account.id,
+    host: caller !== null && view.event.ownerId === caller.account.id,
   };
 }
 
@@ -381,16 +381,29 @@ export async function handleOAuthApi(
         return true;
       }
       const caller = await callerFor(request, options, "parties");
-      if (caller === null) {
+      const rest = path.slice("/api/v1/watch-parties/".length).split("/");
+      const reference = decodeURIComponent(rest[0] ?? "");
+      const action = rest[1];
+      // Reading one party is open, the way its /live/<slug> page is: the code
+      // or the room link IS the invitation, and a person who was handed one
+      // on a television or in a terminal has no session on nixamp.com yet.
+      // Everything else -- the list, bridging, moving playback, ending --
+      // still needs a session or a token with the parties scope.
+      const openRead = path !== "/api/v1/watch-parties" && !action && request.method === "GET";
+      if (caller === null && !openRead) {
         json(response, 401, { error: "a session, or a token granted the parties scope, is needed here" });
         return true;
       }
       // A client bridges parties under its own origin, so two sites cannot
       // collide on a six-character code; a person acting directly is filed
       // under nixamp itself.
-      const origin = caller.clientId || "nixamp";
+      const origin = caller?.clientId || "nixamp";
 
       if (path === "/api/v1/watch-parties") {
+        if (caller === null) {
+          json(response, 401, { error: "a session, or a token granted the parties scope, is needed here" });
+          return true;
+        }
         if (request.method === "GET") {
           const wanted = url.searchParams.get("origin");
           const found = await parties.list({
@@ -424,14 +437,16 @@ export async function handleOAuthApi(
         return true;
       }
 
-      const rest = path.slice("/api/v1/watch-parties/".length).split("/");
-      const reference = decodeURIComponent(rest[0] ?? "");
-      const action = rest[1];
       // A party is findable by its code on the origin that bridged it, or by
       // the nixamp slug or room a client was handed, because a nixamp client
-      // arriving from a share link has only the latter.
-      const view = (await parties.byCode(origin, reference).catch(() => null)) ?? (await parties.byEvent(reference));
-      if (!view) {
+      // arriving from a share link has only the latter. A person on
+      // nixamp.com with only a code gets the party that code names on
+      // whichever site bridged it.
+      const view =
+        (await parties.byCode(origin, reference).catch(() => null)) ??
+        (await parties.byEvent(reference)) ??
+        (caller === null || caller.clientId === "" ? await parties.byAnyCode(reference).catch(() => null) : null);
+      if (!view || (caller === null && view.event.visibility === "private")) {
         json(response, 404, { error: "watch party not found" });
         return true;
       }
@@ -440,6 +455,10 @@ export async function handleOAuthApi(
         json(response, 200, partyBody(parties, view, caller));
         return true;
       }
+      if (caller === null) {
+        json(response, 401, { error: "a session, or a token granted the parties scope, is needed here" });
+        return true;
+      }
       if (action === "playback" && request.method === "POST") {
         let input: Record<string, unknown>;
         try {

package/src/oauth-server.ts

@@ -52,6 +52,7 @@ export const SCOPES = {
   profile: "who you are on nixamp (your handle)",
   email: "the address on your account",
   parties: "host and join watch parties as you",
+  streams: "see the servers you run on nixamp, and what is live on them",
   offline_access: "stay connected without asking again",
 } as const;
 
@@ -83,13 +84,33 @@ export const BITTORRENTED_CLIENT: OAuthClient = {
 };
 
 /**
- * The registered clients: the built-in one, plus whatever NIXAMP_OAUTH_CLIENTS
+ * backtoschool.help runs on this codebase and used to tell its teachers that
+ * their school identity *was* a nixamp account. It is not, any more: a school
+ * account is a school account, and nixamp is the broadcast backend a host may
+ * connect -- through this client, like any other site. Public, PKCE only.
+ */
+export const BACKTOSCHOOL_CLIENT: OAuthClient = {
+  id: "backtoschool",
+  name: "BackToSchool.help",
+  homepage: "https://backtoschool.help",
+  redirectUris: [
+    "https://backtoschool.help/api/v1/nixamp/callback",
+    "https://www.backtoschool.help/api/v1/nixamp/callback",
+    "http://localhost:5174/api/v1/nixamp/callback",
+  ],
+};
+
+/**
+ * The registered clients: the built-in ones, plus whatever NIXAMP_OAUTH_CLIENTS
  * names. The variable is a JSON list of `{id, name, redirectUris, secret?,
  * homepage?}`; an entry with the built-in id replaces it, so a staging
  * bittorrented can point the callback somewhere else.
  */
 export function clientsFrom(env: Record<string, string | undefined>): OAuthClient[] {
-  const byId = new Map<string, OAuthClient>([[BITTORRENTED_CLIENT.id, BITTORRENTED_CLIENT]]);
+  const byId = new Map<string, OAuthClient>([
+    [BITTORRENTED_CLIENT.id, BITTORRENTED_CLIENT],
+    [BACKTOSCHOOL_CLIENT.id, BACKTOSCHOOL_CLIENT],
+  ]);
   const raw = env["NIXAMP_OAUTH_CLIENTS"];
   if (raw) {
     let parsed: unknown = [];
@@ -116,6 +137,7 @@ export function clientsFrom(env: Record<string, string | undefined>): OAuthClien
     }
   }
   if (env["NIXAMP_OAUTH_BITTORRENTED"] === "off") byId.delete(BITTORRENTED_CLIENT.id);
+  if (env["NIXAMP_OAUTH_BACKTOSCHOOL"] === "off") byId.delete(BACKTOSCHOOL_CLIENT.id);
   return [...byId.values()];
 }