nixamp 0.28.37 → 0.28.41

package/dist/nixamp-link.d.ts

@@ -0,0 +1,66 @@
+import type { Queryable } from "./follows.ts";
+import type { LinkView } from "./nixamp-link-types.ts";
+export type { LinkView } from "./nixamp-link-types.ts";
+/** What the school asks nixamp for: who you are, your servers, and to keep it. */
+export declare const LINK_SCOPE = "profile streams offline_access";
+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 declare const NOT_CONNECTED: LinkView;
+/** The real thing: nixamp.com over HTTP. */
+export declare function nixampExchange(issuer: string, clientId: string, fetcher?: typeof fetch): OAuthExchange;
+export declare class NixampLinks {
+    private readonly db;
+    private readonly exchange;
+    private readonly clientId;
+    private readonly now;
+    /** How nixamp.com and the servers it lists are reached, for what the tokens are used on. */
+    readonly fetcher: typeof fetch;
+    private ready;
+    constructor(db: Queryable, exchange: OAuthExchange, clientId: string, now?: () => number, 
+    /** How nixamp.com and the servers it lists are reached, for what the tokens are used on. */
+    fetcher?: typeof fetch);
+    private ensure;
+    /**
+     * 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;
+    };
+    /** The second leg: the code becomes tokens, the tokens say whose, and that is kept. */
+    finish(userId: string, leg: {
+        code: string;
+        verifier: string;
+        redirectUri: string;
+    }): Promise<LinkView>;
+    private expiry;
+    of(userId: string): Promise<LinkView>;
+    /**
+     * 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.
+     */
+    accessToken(userId: string): Promise<string>;
+    /** Withdraw the grant on nixamp.com and forget it here. True when there was one. */
+    disconnect(userId: string): Promise<boolean>;
+}

package/dist/nixamp-link.js

@@ -0,0 +1,231 @@
+/**
+ * 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 { challengeFor } from "./oauth-server.js";
+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 const NOT_CONNECTED = { connected: false, handle: "", nixampUserId: "", scope: "", since: null };
+/** The real thing: nixamp.com over HTTP. */
+export function nixampExchange(issuer, clientId, fetcher = fetch) {
+    const base = issuer.replace(/\/+$/, "");
+    async function post(path, form, accept) {
+        let 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(() => ({})));
+        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;
+        },
+        async userinfo(accessToken) {
+            let 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(() => ({})));
+            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) {
+    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) {
+    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 {
+    db;
+    exchange;
+    clientId;
+    now;
+    fetcher;
+    ready = null;
+    constructor(db, exchange, clientId, now = () => Date.now(), 
+    /** How nixamp.com and the servers it lists are reached, for what the tokens are used on. */
+    fetcher = fetch) {
+        this.db = db;
+        this.exchange = exchange;
+        this.clientId = clientId;
+        this.now = now;
+        this.fetcher = fetcher;
+    }
+    async ensure() {
+        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) {
+        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, leg) {
+        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);
+    }
+    expiry(grant) {
+        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) {
+        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) {
+        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;
+        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) {
+        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/dist/notify.d.ts

@@ -67,17 +67,19 @@ export declare function resendEmail({ apiKey, from, backtoschool, reason, fetch,
 /**
  * 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 declare function webPush({ publicKey, privateKey, subject, onEvent }: {
+export declare function webPush({ 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>;

package/dist/notify.js

@@ -1,3 +1,4 @@
+import { sendPush } from "@profullstack/notifications/server";
 import { mailSender } from "./mail-sender.js";
 /**
  * Tell an audience, on every channel each of them wants.
@@ -93,37 +94,25 @@ function escapeHtml(value) {
 /**
  * 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 }) {
-    let library = null;
-    const load = async () => {
-        library ??= import("web-push").then((mod) => {
-            const wp = (mod["default"] ?? mod);
-            wp.setVapidDetails(subject, publicKey, privateKey);
-            return wp;
-        });
-        return library;
-    };
+export function webPush({ publicKey, privateKey, subject, onEvent, fetch }) {
+    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 });
+        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";
         }
-        catch (error) {
-            const status = error.statusCode;
-            if (status === 404 || status === 410) {
-                onEvent?.(`  push endpoint retired by the vendor, dropping it`);
-                return "gone";
-            }
-            onEvent?.(`  push failed: ${status ?? error.message}`);
-            return "failed";
-        }
+        onEvent?.(`  push failed: ${result.status ?? result.error}`);
+        return "failed";
     };
 }

package/dist/oauth-api.d.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
  *

package/dist/oauth-api.js

@@ -121,7 +121,7 @@ function partyBody(parties, view, caller) {
         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,
     };
 }
 // --- the handler ---------------------------------------------------------------
@@ -282,15 +282,28 @@ export async function handleOAuthApi(request, response, url, options) {
                 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({
@@ -324,14 +337,15 @@ export async function handleOAuthApi(request, response, url, options) {
                 json(response, 405, { error: "GET or POST" });
                 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;
             }
@@ -339,6 +353,10 @@ export async function handleOAuthApi(request, response, url, options) {
                 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;
                 try {

package/dist/oauth-server.d.ts

@@ -18,6 +18,7 @@ export declare const SCOPES: {
     readonly profile: "who you are on nixamp (your handle)";
     readonly email: "the address on your account";
     readonly parties: "host and join watch parties as you";
+    readonly streams: "see the servers you run on nixamp, and what is live on them";
     readonly offline_access: "stay connected without asking again";
 };
 export type Scope = keyof typeof SCOPES;
@@ -35,7 +36,14 @@ export declare const REFRESH_TTL_MS: number;
  */
 export declare 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 declare const BACKTOSCHOOL_CLIENT: OAuthClient;
+/**
+ * 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.

package/dist/oauth-server.js

@@ -34,6 +34,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",
 };
 export const SCOPE_NAMES = Object.keys(SCOPES);
@@ -59,13 +60,32 @@ export const BITTORRENTED_CLIENT = {
     ],
 };
 /**
- * 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 = {
+    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) {
-    const byId = new Map([[BITTORRENTED_CLIENT.id, BITTORRENTED_CLIENT]]);
+    const byId = new Map([
+        [BITTORRENTED_CLIENT.id, BITTORRENTED_CLIENT],
+        [BACKTOSCHOOL_CLIENT.id, BACKTOSCHOOL_CLIENT],
+    ]);
     const raw = env["NIXAMP_OAUTH_CLIENTS"];
     if (raw) {
         let parsed = [];
@@ -95,6 +115,8 @@ export function clientsFrom(env) {
     }
     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()];
 }
 /** Loopback is the address; the port is whatever the CLI got (RFC 8252 §7.3). */

package/dist/profiles.d.ts

@@ -0,0 +1,85 @@
+import type { Queryable } from "./follows.ts";
+/** The card as the account holder sees it. */
+export interface Profile {
+    name: string;
+    homepage: string;
+    /** A picture somewhere on the web, when they gave one instead of uploading. */
+    avatarUrl: string;
+    bio: string;
+    /** Set when a photo is stored here; the etag changes with the bytes. */
+    photo: string;
+}
+export interface ProfileInput {
+    name?: unknown;
+    homepage?: unknown;
+    avatarUrl?: unknown;
+    bio?: unknown;
+}
+/** What a classroom shows about its host. */
+export interface HostCard {
+    hostName: string;
+    homepageUrl: string;
+    avatarUrl: string;
+}
+export declare const EMPTY_PROFILE: Profile;
+/** A photo is a picture, not a document: a megabyte is plenty for a face. */
+export declare const PHOTO_LIMIT: number;
+export declare const NAME_LIMIT = 100;
+export declare const BIO_LIMIT = 1000;
+/**
+ * The type is read from the bytes, never from the header: a browser sends
+ * whatever it was told, and what is served back must be what the file is.
+ */
+export declare function sniffImage(bytes: Uint8Array): string;
+/**
+ * What may be written. Every field is optional and what is not sent is
+ * kept; an empty string clears. A link must be https without credentials,
+ * the same rule a classroom applies, so a card never fails at class time.
+ */
+export declare function cleanProfile(input: ProfileInput): {
+    fields: Partial<Profile>;
+    error: string;
+};
+/**
+ * The parts of an OpenProfile.md that say who somebody is: the `#` line is
+ * the name, the identity block gives `Avatar` and `Web`, the first prose
+ * line is the headline, and the first bullet under `## Photos` stands in
+ * for a missing Avatar. Everything else is somebody else's business.
+ */
+export declare function readOpenProfile(markdown: string): Partial<Profile>;
+/** The three things a classroom shows, from the card, with a stored photo served from here. */
+export declare function hostCard(profile: Profile, userId: string, site: string): HostCard;
+export declare class AccountProfiles {
+    private readonly db;
+    private readonly fetcher;
+    private ready;
+    constructor(db: Queryable, fetcher?: typeof fetch);
+    private ensure;
+    of(userId: string): Promise<Profile>;
+    /** Write what was sent, keep what was not. */
+    set(userId: string, input: ProfileInput): Promise<{
+        profile: Profile | null;
+        error: string;
+    }>;
+    /** Keep a photo. The type comes from the bytes; a file that is not a picture is refused. */
+    setPhoto(userId: string, bytes: Uint8Array): Promise<{
+        profile: Profile | null;
+        error: string;
+    }>;
+    removePhoto(userId: string): Promise<Profile>;
+    /** The stored photo, to serve. Null when there is none. */
+    photo(userId: string): Promise<{
+        bytes: Uint8Array;
+        type: string;
+        etag: string;
+    } | null>;
+    /**
+     * Fill the card from an OpenProfile.md. What the file says replaces what
+     * is here; what the file does not say is kept. A stored photo stays: an
+     * Avatar link is only used where no photo was uploaded.
+     */
+    importFrom(userId: string, url: string): Promise<{
+        profile: Profile | null;
+        error: string;
+    }>;
+}