@agent-custody/receipts 0.6.6 → 0.6.8

package/dist/cli.js

@@ -267,9 +267,18 @@ async function main(argv) {
             return 0;
         }
         case "portal": {
-            const { values } = parseArgs({ args: rest, options: { "db-env": { type: "string" }, "secret-env": { type: "string" }, "public-url": { type: "string" }, "checkpoints-url": { type: "string" }, "portal-url": { type: "string" }, port: { type: "string", default: "8792" }, host: { type: "string", default: "127.0.0.1" }, "stripe-key-env": { type: "string" }, "stripe-webhook-env": { type: "string" }, "stripe-price-team": { type: "string" }, "trust-proxy": { type: "boolean", default: false } } });
+            const { values } = parseArgs({ args: rest, options: { "db-env": { type: "string" }, "secret-env": { type: "string" }, "public-url": { type: "string" }, "checkpoints-url": { type: "string" }, "portal-url": { type: "string" }, port: { type: "string", default: "8792" }, host: { type: "string", default: "127.0.0.1" }, "stripe-key-env": { type: "string" }, "stripe-webhook-env": { type: "string" }, "stripe-price-team": { type: "string" }, "mail-key-env": { type: "string" }, "mail-from": { type: "string" }, "mail-notify": { type: "string" }, "trust-proxy": { type: "boolean", default: false } } });
             if (!values["db-env"] || !values["secret-env"] || !values["public-url"])
                 throw new Error("portal needs --db-env, --secret-env, and --public-url");
+            let mail;
+            if (values["mail-key-env"] || values["mail-from"]) {
+                if (!values["mail-key-env"] || !values["mail-from"])
+                    throw new Error("mail needs both --mail-key-env and --mail-from");
+                const apiKey = process.env[values["mail-key-env"]];
+                if (!apiKey)
+                    throw new Error(`portal: environment variable ${values["mail-key-env"]} is not set`);
+                mail = { apiKey, from: values["mail-from"], ...(values["mail-notify"] ? { notify: values["mail-notify"] } : {}) };
+            }
             const secret = process.env[values["secret-env"]];
             if (!secret || secret.length < 32)
                 throw new Error(`environment variable ${values["secret-env"]} must hold a secret of at least 32 characters`);
@@ -292,7 +301,7 @@ async function main(argv) {
             catch {
                 // the log may not be reachable from here at start; the sheet then omits the keyid
             }
-            const running = await servePortal({ tenancy, client, secret, publicUrl: values["public-url"], ...(values["checkpoints-url"] ? { checkpointsUrl: values["checkpoints-url"] } : {}), ...(values["portal-url"] ? { portalUrl: values["portal-url"] } : {}), ...(keyid ? { keyid } : {}), ...(stripe ? { stripe } : {}), trustProxy: values["trust-proxy"] }, { port: Number(values.port), host: values.host });
+            const running = await servePortal({ tenancy, client, secret, publicUrl: values["public-url"], ...(values["checkpoints-url"] ? { checkpointsUrl: values["checkpoints-url"] } : {}), ...(values["portal-url"] ? { portalUrl: values["portal-url"] } : {}), ...(keyid ? { keyid } : {}), ...(stripe ? { stripe } : {}), ...(mail ? { mail } : {}), trustProxy: values["trust-proxy"] }, { port: Number(values.port), host: values.host });
             console.error(`agent-custody portal: ${running.url} log=${values["public-url"]} billing=${stripe ? "stripe" : "off"}${values["trust-proxy"] ? " trust-proxy" : ""}`);
             await new Promise((resolve) => process.once("SIGINT", resolve));
             await running.close();

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { openExporter, otlpExporter, spanFor } from "./otel.ts";
 export { hecEvent, splunkExporter } from "./splunk.ts";
 export { GRANT_HEADER, grantHeader, parseGrantHeader, serveHttp } from "./gateway-http.ts";
 export { PortalStore, portalHandler, readSession, servePortal, signSession, stripeRequest, verifyStripeSignature } from "./portal.ts";
-export type { PortalOptions, PortalUser, RunningPortal, StripeOptions } from "./portal.ts";
+export type { MailOptions, PortalOptions, PortalUser, Profile, RunningPortal, StripeOptions } from "./portal.ts";
 export type { HttpGatewayOptions, RunningHttpGateway } from "./gateway-http.ts";
 export { exportLog, formatExport } from "./log-export.ts";
 export type { ExportOptions, ExportResult } from "./log-export.ts";

package/dist/log-admin.d.ts

@@ -36,7 +36,7 @@ export declare function welcomeSheet(o: {
  *   POST /admin/tenants/:id/tokens/:prefix/revoke { revoked }
  *   GET  /admin/usage?month=YYYY-MM              { month, tenants: [{ id, logId, appends, totalLeaves, liveTokens, disabled }] }
  *   GET  /admin/usage.csv?month=YYYY-MM          the same as CSV, for an invoice
- *   GET  /admin/registrations?month=YYYY-MM      { month, rows: [{ tenant, logId, plan, email, registeredAt, billing, appends, quota, totalLeaves, liveTokens, disabled }], totals }
+ *   GET  /admin/registrations?month=YYYY-MM      { month, rows: [{ tenant, logId, plan, email, name, company, role, phone, telegram, registeredAt, billing, appends, quota, totalLeaves, liveTokens, disabled }], totals }
  *   GET  /admin/registrations.csv?month=YYYY-MM  the same as CSV
  */
 /** One row per tenant: who registered it through the portal (null when it was onboarded by script), its plan and billing
@@ -56,6 +56,11 @@ export interface RegistrationRow {
     logId: string;
     plan: Plan;
     email: string | null;
+    name: string | null;
+    company: string | null;
+    role: string | null;
+    phone: string | null;
+    telegram: string | null;
     registeredAt: string | null;
     billing: string | null;
     appends: number;

package/dist/log-admin.js

@@ -57,7 +57,7 @@ export function welcomeSheet(o) {
  *   POST /admin/tenants/:id/tokens/:prefix/revoke { revoked }
  *   GET  /admin/usage?month=YYYY-MM              { month, tenants: [{ id, logId, appends, totalLeaves, liveTokens, disabled }] }
  *   GET  /admin/usage.csv?month=YYYY-MM          the same as CSV, for an invoice
- *   GET  /admin/registrations?month=YYYY-MM      { month, rows: [{ tenant, logId, plan, email, registeredAt, billing, appends, quota, totalLeaves, liveTokens, disabled }], totals }
+ *   GET  /admin/registrations?month=YYYY-MM      { month, rows: [{ tenant, logId, plan, email, name, company, role, phone, telegram, registeredAt, billing, appends, quota, totalLeaves, liveTokens, disabled }], totals }
  *   GET  /admin/registrations.csv?month=YYYY-MM  the same as CSV
  */
 /** One row per tenant: who registered it through the portal (null when it was onboarded by script), its plan and billing
@@ -70,7 +70,7 @@ export async function registrations(tenancy, portal, month) {
             who.set(r.tenantId, r);
     const rows = usage.tenants.map((t) => {
         const w = who.get(t.id);
-        return { tenant: t.id, logId: t.logId, plan: t.plan, email: w?.email ?? null, registeredAt: w?.registeredAt ?? null, billing: w?.billing ?? null, appends: t.appends, quota: t.quota, totalLeaves: t.totalLeaves, liveTokens: t.liveTokens, disabled: t.disabled };
+        return { tenant: t.id, logId: t.logId, plan: t.plan, email: w?.email ?? null, name: w?.name ?? null, company: w?.company ?? null, role: w?.role ?? null, phone: w?.phone ?? null, telegram: w?.telegram ?? null, registeredAt: w?.registeredAt ?? null, billing: w?.billing ?? null, appends: t.appends, quota: t.quota, totalLeaves: t.totalLeaves, liveTokens: t.liveTokens, disabled: t.disabled };
     });
     return { month: usage.month, rows, totals: { tenants: rows.length, registered: rows.filter((r) => r.email).length, appends: rows.reduce((n, r) => n + r.appends, 0), totalLeaves: rows.reduce((n, r) => n + r.totalLeaves, 0) } };
 }
@@ -140,7 +140,7 @@ export function adminRoutes(opts) {
             else if (req.method === "GET" && parts.length === 2 && parts[1] === "registrations.csv") {
                 const r = await registrations(t, opts.portal, month);
                 const cell = (v) => (v === null ? "" : /[",\n]/.test(String(v)) ? `"${String(v).replace(/"/g, '""')}"` : String(v));
-                const csv = ["month,tenant,log_id,plan,email,registered_at,billing,appends,quota,total_leaves,live_tokens,disabled", ...r.rows.map((x) => [r.month, x.tenant, x.logId, x.plan, x.email, x.registeredAt, x.billing, x.appends, x.quota, x.totalLeaves, x.liveTokens, x.disabled].map(cell).join(","))].join("\n") + "\n";
+                const csv = ["month,tenant,log_id,plan,email,name,company,role,phone,telegram,registered_at,billing,appends,quota,total_leaves,live_tokens,disabled", ...r.rows.map((x) => [r.month, x.tenant, x.logId, x.plan, x.email, x.name, x.company, x.role, x.phone, x.telegram, x.registeredAt, x.billing, x.appends, x.quota, x.totalLeaves, x.liveTokens, x.disabled].map(cell).join(","))].join("\n") + "\n";
                 res.writeHead(200, { "content-type": "text/csv; charset=utf-8", "content-disposition": `attachment; filename="agent-custody-registrations-${r.month}.csv"`, "cache-control": "no-store" });
                 res.end(csv);
             }
@@ -237,7 +237,7 @@ const ADMIN_PAGE = `<!doctype html>
     <h2>Registrations</h2>
     <div class="row"><label>month<input id="rmonth" type="month"></label><button class="quiet" id="loadRegs">Show</button><a id="rcsv" class="quiet" href="#" style="align-self:center">Download CSV</a></div>
     <div class="stats"><div class="stat"><b id="sTenants">–</b><span>tenants</span></div><div class="stat"><b id="sRegistered">–</b><span>registered through the portal</span></div><div class="stat"><b id="sAppends">–</b><span>appends this month</span></div><div class="stat"><b id="sLeaves">–</b><span>leaves in total</span></div></div>
-    <table><thead><tr><th>email</th><th>tenant</th><th>plan</th><th>registered</th><th>billing</th><th>appends this month</th><th>leaves in total</th><th>live tokens</th></tr></thead><tbody id="regs"></tbody></table>
+    <table><thead><tr><th>who</th><th>reach</th><th>tenant</th><th>plan</th><th>registered</th><th>billing</th><th>appends this month</th><th>leaves in total</th><th>live tokens</th></tr></thead><tbody id="regs"></tbody></table>
     <h2>Tenants</h2>
     <table><thead><tr><th>tenant</th><th>log id</th><th>plan</th><th>live tokens</th><th>created</th><th></th></tr></thead><tbody id="tenants"></tbody></table>
     <h2>New tenant</h2>
@@ -326,7 +326,9 @@ const ADMIN_PAGE = `<!doctype html>
     const r = await api("GET", "/admin/registrations?month=" + encodeURIComponent(month));
     $("rcsv").href = "/admin/registrations.csv?month=" + encodeURIComponent(month);
     $("sTenants").textContent = r.totals.tenants; $("sRegistered").textContent = r.totals.registered; $("sAppends").textContent = r.totals.appends; $("sLeaves").textContent = r.totals.totalLeaves;
-    $("regs").innerHTML = r.rows.map((x) => "<tr><td>" + (x.email ? esc(x.email) : "<span class=muted>onboarded by script</span>") + "</td><td><code>" + esc(x.tenant) + "</code>" + (x.disabled ? " <span class=muted>disabled</span>" : "") + "</td><td>" + esc(x.plan) + "</td><td>" + (x.registeredAt ? esc(x.registeredAt.slice(0, 10)) : "") + "</td><td>" + (x.billing ? esc(x.billing) : "<span class=muted>none</span>") + "</td><td>" + x.appends + (x.quota === null ? "" : " <span class=muted>/ " + x.quota + "</span>") + "</td><td>" + x.totalLeaves + "</td><td>" + x.liveTokens + "</td></tr>").join("") || "<tr><td colspan=8 class=muted>no tenants</td></tr>";
+    const who = (x) => x.email ? esc(x.name || "") + (x.company ? " <span class=muted>· " + esc(x.company) + (x.role ? ", " + esc(x.role) : "") + "</span>" : "") : "<span class=muted>onboarded by script</span>";
+    const reach = (x) => [x.email ? "<a href=\"mailto:" + esc(x.email) + "\">" + esc(x.email) + "</a>" : "", x.phone ? esc(x.phone) : "", x.telegram ? "telegram @" + esc(x.telegram) : ""].filter(Boolean).join("<br>");
+    $("regs").innerHTML = r.rows.map((x) => "<tr><td>" + who(x) + "</td><td>" + reach(x) + "</td><td><code>" + esc(x.tenant) + "</code>" + (x.disabled ? " <span class=muted>disabled</span>" : "") + "</td><td>" + esc(x.plan) + "</td><td>" + (x.registeredAt ? esc(x.registeredAt.slice(0, 10)) : "") + "</td><td>" + (x.billing ? esc(x.billing) : "<span class=muted>none</span>") + "</td><td>" + x.appends + (x.quota === null ? "" : " <span class=muted>/ " + x.quota + "</span>") + "</td><td>" + x.totalLeaves + "</td><td>" + x.liveTokens + "</td></tr>").join("") || "<tr><td colspan=9 class=muted>no tenants</td></tr>";
   };
   const loadAudit = async () => {
     const a = await api("GET", "/admin/audit?limit=100");

package/dist/portal.d.ts

@@ -7,6 +7,17 @@ export interface StripeOptions {
     priceTeam: string;
     fetch?: typeof fetch;
 }
+/** Outbound mail over an HTTP API in Resend's shape (`POST /emails` with a bearer key). One message at registration; never a secret. */
+export interface MailOptions {
+    apiKey: string;
+    /** the sender, an address on a domain the provider has verified */
+    from: string;
+    /** an operator address that gets a note per registration, with the contact details */
+    notify?: string;
+    /** the endpoint; Resend's by default */
+    url?: string;
+    fetch?: typeof fetch;
+}
 export interface PortalOptions {
     tenancy: PostgresTenancy;
     /** the Postgres client the tenancy uses; the portal's own tables live beside the log's */
@@ -21,6 +32,7 @@ export interface PortalOptions {
     /** the portal's own public URL, for Stripe's return addresses */
     portalUrl?: string;
     stripe?: StripeOptions;
+    mail?: MailOptions;
     /** key throttles by X-Forwarded-For; only behind a proxy you run. Also marks cookies Secure. */
     trustProxy?: boolean;
     /** table prefix; default portal_ */
@@ -33,6 +45,14 @@ export interface PortalUser {
     createdAt: string;
 }
 /** Users, memberships, and billing records, beside the log's tables. */
+/** What a registration says about the person and the organisation; every field optional in the store, the route decides what it requires. */
+export interface Profile {
+    name?: string | null;
+    company?: string | null;
+    role?: string | null;
+    phone?: string | null;
+    telegram?: string | null;
+}
 export declare class PortalStore {
     private readonly client;
     private readonly p;
@@ -41,7 +61,7 @@ export declare class PortalStore {
     private init;
     static hashPassword(password: string): string;
     static checkPassword(password: string, stored: string): boolean;
-    createUser(email: string, password: string): Promise<PortalUser>;
+    createUser(email: string, password: string, profile?: Profile): Promise<PortalUser>;
     authenticate(email: string, password: string): Promise<PortalUser | null>;
     user(id: string): Promise<PortalUser | null>;
     addMember(userId: string, tenantId: string): Promise<void>;
@@ -58,12 +78,12 @@ export declare class PortalStore {
         status: string;
     } | null>;
     /** Every portal registration with its tenant and billing state, oldest first: what the operator's admin page lists. */
-    registrations(): Promise<{
+    registrations(): Promise<({
         tenantId: string;
         email: string;
         registeredAt: string;
         billing: string | null;
-    }[]>;
+    } & Profile)[]>;
     tenantBySubscription(subscriptionId: string): Promise<string | null>;
 }
 export declare function signSession(secret: string, userId: string, ttlMs?: number): string;

package/dist/portal.js

@@ -19,7 +19,7 @@ const ident = (s) => {
         throw new Error(`prefix must be a plain identifier; got "${s}"`);
     return s;
 };
-/** Users, memberships, and billing records, beside the log's tables. */
+const PROFILE_COLUMNS = ["name", "company", "role", "phone", "telegram"];
 export class PortalStore {
     client;
     p;
@@ -36,6 +36,9 @@ export class PortalStore {
                 await this.client.query(`CREATE TABLE IF NOT EXISTS ${p}users (id TEXT PRIMARY KEY, email TEXT NOT NULL UNIQUE, password_hash TEXT NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT now())`);
                 await this.client.query(`CREATE TABLE IF NOT EXISTS ${p}members (user_id TEXT NOT NULL REFERENCES ${p}users(id), tenant_id TEXT NOT NULL, role TEXT NOT NULL DEFAULT 'owner', created_at TIMESTAMPTZ NOT NULL DEFAULT now(), PRIMARY KEY (user_id, tenant_id))`);
                 await this.client.query(`CREATE TABLE IF NOT EXISTS ${p}billing (tenant_id TEXT PRIMARY KEY, customer_id TEXT, subscription_id TEXT, status TEXT NOT NULL, updated_at TIMESTAMPTZ NOT NULL DEFAULT now())`);
+                // who the account belongs to: added after the first tenants registered, so the columns are optional
+                for (const c of PROFILE_COLUMNS)
+                    await this.client.query(`ALTER TABLE ${p}users ADD COLUMN IF NOT EXISTS ${c} TEXT`);
             })();
         }
         return this.ready;
@@ -52,10 +55,10 @@ export class PortalStore {
         const got = scryptSync(password, Buffer.from(saltHex, "hex"), expected.length);
         return got.length === expected.length && timingSafeEqual(got, expected);
     }
-    async createUser(email, password) {
+    async createUser(email, password, profile = {}) {
         await this.init();
         const id = randomUUID();
-        const rows = (await this.client.query(`INSERT INTO ${this.p}users (id, email, password_hash) VALUES ($1, $2, $3) ON CONFLICT (email) DO NOTHING RETURNING id, email, created_at`, [id, email, PortalStore.hashPassword(password)])).rows;
+        const rows = (await this.client.query(`INSERT INTO ${this.p}users (id, email, password_hash, name, company, role, phone, telegram) VALUES ($1, $2, $3, $4, $5, $6, $7, $8) ON CONFLICT (email) DO NOTHING RETURNING id, email, created_at`, [id, email, PortalStore.hashPassword(password), profile.name ?? null, profile.company ?? null, profile.role ?? null, profile.phone ?? null, profile.telegram ?? null])).rows;
         if (!rows[0])
             throw new Error("an account with this email already exists");
         return { id, email, createdAt: new Date(rows[0].created_at).toISOString() };
@@ -98,8 +101,9 @@ export class PortalStore {
     /** Every portal registration with its tenant and billing state, oldest first: what the operator's admin page lists. */
     async registrations() {
         await this.init();
-        const rows = (await this.client.query(`SELECT m.tenant_id, u.email, u.created_at, b.status FROM ${this.p}members m JOIN ${this.p}users u ON u.id = m.user_id LEFT JOIN ${this.p}billing b ON b.tenant_id = m.tenant_id ORDER BY u.created_at, m.tenant_id`)).rows;
-        return rows.map((r) => ({ tenantId: String(r.tenant_id), email: String(r.email), registeredAt: new Date(r.created_at).toISOString(), billing: r.status ? String(r.status) : null }));
+        const rows = (await this.client.query(`SELECT m.tenant_id, u.email, u.created_at, u.name, u.company, u.role, u.phone, u.telegram, b.status FROM ${this.p}members m JOIN ${this.p}users u ON u.id = m.user_id LEFT JOIN ${this.p}billing b ON b.tenant_id = m.tenant_id ORDER BY u.created_at, m.tenant_id`)).rows;
+        const str = (v) => (v == null ? null : String(v));
+        return rows.map((r) => ({ tenantId: String(r.tenant_id), email: String(r.email), registeredAt: new Date(r.created_at).toISOString(), billing: str(r.status), name: str(r.name), company: str(r.company), role: str(r.role), phone: str(r.phone), telegram: str(r.telegram) }));
     }
     async tenantBySubscription(subscriptionId) {
         await this.init();
@@ -169,7 +173,46 @@ export function portalHandler(o) {
     const base = o.publicUrl.endsWith("/") ? o.publicUrl : `${o.publicUrl}/`;
     const cookieName = "custody_session";
     const sheet = (tenant, logId) => welcomeSheet({ tenant, logId, publicUrl: base, ...(o.checkpointsUrl ? { checkpointsUrl: o.checkpointsUrl } : {}), ...(o.keyid ? { keyid: o.keyid } : {}) });
+    const portalBase = (o.portalUrl ?? "http://localhost/").replace(/\/?$/, "/");
+    // Mail is best effort and off the request path: a provider outage is logged, never a failed registration.
+    const send = async (m) => {
+        if (!o.mail)
+            return;
+        const f = o.mail.fetch ?? fetch;
+        try {
+            const r = await f(o.mail.url ?? "https://api.resend.com/emails", { method: "POST", headers: { authorization: `Bearer ${o.mail.apiKey}`, "content-type": "application/json" }, body: JSON.stringify({ from: o.mail.from, to: [m.to], subject: m.subject, text: m.text }), signal: AbortSignal.timeout(10_000) });
+            if (!r.ok)
+                log(`agent-custody portal: mail to ${m.to} refused: ${r.status} ${(await r.text()).slice(0, 200)}`);
+        }
+        catch (e) {
+            log(`agent-custody portal: mail to ${m.to} failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    };
+    const welcomeMail = (to, name, tenant, logId) => send({ to, subject: `Your agent-custody log "${tenant}" is ready`, text: [
+            `Hello ${name},`, "",
+            `Your tenant "${tenant}" is live on the hosted log. Your API key was shown once when you registered and is not in this email; if it is gone, mint another under API keys at ${portalBase}.`, "",
+            "Everything below is under Setup in the dashboard whenever you need it.", "",
+            sheet(tenant, logId), "",
+            `Dashboard: ${portalBase}`, "Getting started: https://agent-custody.dev/guide/getting-started", "Questions: reply to this email.",
+        ].join("\n") });
+    const notifyMail = (p) => o.mail?.notify ? send({ to: o.mail.notify, subject: `New registration: ${p.company} (${p.tenant})`, text: [`${p.name}${p.role ? `, ${p.role}` : ""} at ${p.company} registered tenant "${p.tenant}".`, "", `email     ${p.email}`, `phone     ${p.phone ?? "-"}`, `telegram  ${p.telegram ? `@${p.telegram}` : "-"}`, "", "The Registrations section of the admin page has the same, with their usage."].join("\n") }) : Promise.resolve();
     const exportCommand = (tenant) => `npx @agent-custody/receipts log-export --log-url ${base} --tenant ${tenant} --token-env AGENT_CUSTODY_LOG_TOKEN --out custody-export/`;
+    // The welcome sheet as data: what the page renders as numbered steps, at registration and again under Setup.
+    const setupFor = (tenant, logId) => {
+        const url = `${base}t/${tenant}/`;
+        return {
+            log: url,
+            logId,
+            checkpoints: o.checkpointsUrl ? `${o.checkpointsUrl.replace(/\/?$/, "/")}${tenant}/latest.json` : null,
+            keys: `${base}.well-known/agent-custody-log.json`,
+            keyid: o.keyid ?? null,
+            env: "export AGENT_CUSTODY_LOG_TOKEN=<the key shown at registration>",
+            config: `"log": { "url": "${url}", "tokenEnv": "AGENT_CUSTODY_LOG_TOKEN", "hashOnly": true }`,
+            verify: `npx @agent-custody/receipts verify receipts/<id>.json --issuer-key <your gateway.pub> --principal-key <your principal.pub> --log-url ${url} --log-id ${logId}`,
+            audit: `npx @agent-custody/receipts audit --older receipts/<earlier>.json --newer receipts/<later>.json --log-url ${url} --log-id ${logId}`,
+            export: exportCommand(tenant),
+        };
+    };
     return async (req, res) => {
         const url = new URL(req.url ?? "/", "http://localhost");
         const addr = clientAddress(req, o.trustProxy);
@@ -200,7 +243,7 @@ export function portalHandler(o) {
                 return json(200, { ok: true, stripe: !!o.stripe });
             if (req.method === "GET" && url.pathname === "/") {
                 res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", "x-frame-options": "DENY", "content-security-policy": "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; form-action 'self'; base-uri 'none'" });
-                return void res.end(PORTAL_PAGE);
+                return void res.end(PORTAL_PAGE.replace("__LOG_BASE__", base.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c])));
             }
             // ---- Stripe's webhook: the only caller that is not a browser with a session ----
             if (req.method === "POST" && url.pathname === "/stripe/webhook") {
@@ -234,8 +277,6 @@ export function portalHandler(o) {
             }
             // ---- registration and login ----
             if (req.method === "POST" && url.pathname === "/api/register") {
-                if (!registrations.take(`reg:${addr}`))
-                    return json(429, { error: "too many registrations from this address; try again later" });
                 const b = await jsonBody();
                 const email = String(b.email ?? "").trim().toLowerCase();
                 const password = String(b.password ?? "");
@@ -246,11 +287,24 @@ export function portalHandler(o) {
                     return json(400, { error: "the password needs at least ten characters" });
                 if (!TENANT_ID.test(tenant) || RESERVED.has(tenant))
                     return json(400, { error: "the tenant id is the name in your log's URL: three to forty lowercase letters, digits, or hyphens, and not a reserved word" });
+                const text = (k, max) => String(b[k] ?? "").trim().slice(0, max);
+                const profile = { name: text("name", 120), company: text("company", 160), role: text("role", 120) || null, phone: text("phone", 40) || null, telegram: text("telegram", 40).replace(/^@/, "") || null };
+                if (!profile.name)
+                    return json(400, { error: "your name is needed, so we know who to write to" });
+                if (!profile.company)
+                    return json(400, { error: "the company or organisation the tenant is for is needed" });
+                if (profile.telegram && !/^[A-Za-z0-9_]{5,32}$/.test(profile.telegram))
+                    return json(400, { error: "a Telegram username is five to thirty-two letters, digits, or underscores, with or without the @" });
+                if (profile.phone && !/^[+0-9 ()./-]{6,40}$/.test(profile.phone))
+                    return json(400, { error: "a phone number is digits, with an optional + and spaces" });
                 if (await o.tenancy.tenant(tenant))
                     return json(409, { error: "that tenant id is taken" });
+                // throttled once the request is well formed: a mistyped form costs nothing, five real registrations from one address, then one every ten minutes
+                if (!registrations.take(`reg:${addr}`))
+                    return json(429, { error: "too many registrations from this address; try again later" });
                 let user;
                 try {
-                    user = await store.createUser(email, password);
+                    user = await store.createUser(email, password, profile);
                 }
                 catch (e) {
                     return json(409, { error: e instanceof Error ? e.message : String(e) });
@@ -259,7 +313,9 @@ export function portalHandler(o) {
                 await store.addMember(user.id, tenant);
                 const minted = await o.tenancy.addToken(tenant, "first key", `portal:${email}`);
                 log(`agent-custody portal: ${email} registered tenant ${tenant}`);
-                return json(200, { tenant: t.id, logId: t.logId, plan: t.plan, token: minted.token, tokenHash: minted.tokenHash.slice(0, 12), welcome: sheet(t.id, t.logId), exportCommand: exportCommand(t.id) }, { "set-cookie": setCookie(signSession(o.secret, user.id)) });
+                void welcomeMail(email, profile.name, t.id, t.logId);
+                void notifyMail({ ...profile, email, tenant: t.id });
+                return json(200, { tenant: t.id, logId: t.logId, plan: t.plan, token: minted.token, tokenHash: minted.tokenHash.slice(0, 12), welcome: sheet(t.id, t.logId), setup: setupFor(t.id, t.logId), exportCommand: exportCommand(t.id) }, { "set-cookie": setCookie(signSession(o.secret, user.id)) });
             }
             if (req.method === "POST" && url.pathname === "/api/login") {
                 if (!loginFailures.take(`login:${addr}`))
@@ -305,7 +361,7 @@ export function portalHandler(o) {
                 const keys = (await o.tenancy.listTokens(tenantId)).map((k) => ({ label: k.label, hash: k.tokenHash.slice(0, 12), createdAt: k.createdAt, revokedAt: k.revokedAt }));
                 const audit = await o.tenancy.audit({ tenant: tenantId, limit: 50 });
                 const billing = await store.billing(tenantId);
-                return json(200, { tenant: tenantId, logId: tenant.logId, plan: q.plan, used: q.used, quota: q.quota, treeSize: size, rootHash: size ? await backend.root(size) : null, latestCheckpoint: latest ? { treeSize: latest.treeSize, signedAt: latest.signedAt } : null, months, keys, audit, billing: billing ? { status: billing.status } : null, urls: { log: `${base}t/${tenantId}/`, keys: `${base}.well-known/agent-custody-log.json`, checkpoints: o.checkpointsUrl ? `${o.checkpointsUrl.replace(/\/?$/, "/")}${tenantId}/latest.json` : null }, exportCommand: exportCommand(tenantId), welcome: sheet(tenantId, tenant.logId), stripe: !!o.stripe });
+                return json(200, { tenant: tenantId, logId: tenant.logId, plan: q.plan, used: q.used, quota: q.quota, treeSize: size, rootHash: size ? await backend.root(size) : null, latestCheckpoint: latest ? { treeSize: latest.treeSize, signedAt: latest.signedAt } : null, months, keys, audit, billing: billing ? { status: billing.status } : null, urls: { log: `${base}t/${tenantId}/`, keys: `${base}.well-known/agent-custody-log.json`, checkpoints: o.checkpointsUrl ? `${o.checkpointsUrl.replace(/\/?$/, "/")}${tenantId}/latest.json` : null }, exportCommand: exportCommand(tenantId), welcome: sheet(tenantId, tenant.logId), setup: setupFor(tenantId, tenant.logId), stripe: !!o.stripe });
             }
             if (req.method === "GET" && url.pathname === "/api/keys") {
                 return json(200, { keys: (await o.tenancy.listTokens(tenantId)).map((k) => ({ label: k.label, hash: k.tokenHash.slice(0, 12), createdAt: k.createdAt, revokedAt: k.revokedAt })) });
@@ -399,11 +455,19 @@ const PORTAL_PAGE = `<!doctype html>
   .bar i { display: block; width: 70%; background: var(--accent); border-radius: 3px 3px 0 0; min-height: 2px; }
   .bar b { font-family: var(--mono); font-weight: 400; margin-top: .3rem; }
   label { display: grid; gap: .25rem; font-size: .85rem; color: var(--ink2); margin: 0 0 .8rem; }
+  label .opt { font-size: .72rem; text-transform: uppercase; letter-spacing: .06em; margin-left: .3rem; } label .hint { font-size: .8rem; line-height: 1.45; } label .hint code { font-family: var(--mono); font-size: .9em; }
   input, select { font: inherit; padding: .5rem .6rem; border: 1px solid var(--line); border-radius: 4px; background: var(--bg); color: var(--ink); }
   button { font: inherit; padding: .5rem .9rem; border-radius: 4px; border: 1px solid var(--accent); background: var(--accent); color: #fff; cursor: pointer; }
   button.quiet { background: transparent; color: var(--accent); }
   button.link { background: none; border: 0; padding: 0; color: var(--accent); text-decoration: underline; }
   .auth { max-width: 26rem; margin: 4rem auto; }
+  .auth.wide { max-width: 44rem; }
+  .step { display: grid; grid-template-columns: 2rem 1fr; gap: .2rem .8rem; padding: 1rem 0; border-top: 1px solid var(--line); }
+  .step .n { font: 700 .85rem/1.6 var(--mono); color: var(--accent); }
+  .step h3 { margin: 0 0 .3rem; font-size: 1rem; } .step p { margin: 0 0 .5rem; color: var(--ink2); font-size: .92rem; }
+  .snip { position: relative; margin: .4rem 0 .6rem; } .snip pre { margin: 0; padding-right: 4.5rem; font-family: var(--mono); font-size: .84rem; }
+  .snip button { position: absolute; top: .45rem; right: .45rem; padding: .2rem .6rem; font-size: .8rem; }
+  .addr th { text-align: left; font-weight: 600; padding-right: 1rem; white-space: nowrap; } .addr td { word-break: break-all; }
   .once { border: 1px solid var(--warn); background: color-mix(in srgb, var(--warn) 10%, var(--panel)); border-radius: 6px; padding: 1rem 1.1rem; margin: 1rem 0; }
   .tok { font-family: var(--mono); word-break: break-all; padding: .6rem; background: var(--bg); border-radius: 4px; }
   .msg { min-height: 1.4rem; margin: .6rem 0; color: var(--ink2); } .msg.err { color: var(--bad); } .msg.ok { color: var(--ok); }
@@ -415,21 +479,30 @@ const PORTAL_PAGE = `<!doctype html>
 <section id="auth" class="auth" hidden>
   <h1 id="authTitle">Sign in</h1>
   <form id="authForm">
-    <label>Email<input id="email" type="email" autocomplete="email" required></label>
+    <div id="regFields" hidden>
+      <label>Your name<input id="name" autocomplete="name" maxlength="120"></label>
+      <label>Company or organisation<input id="company" autocomplete="organization" maxlength="160"></label>
+      <label>Your role <span class="opt">optional</span><input id="role" autocomplete="organization-title" maxlength="120" placeholder="Head of Platform"></label>
+    </div>
+    <label>Work email<input id="email" type="email" autocomplete="email" required></label>
+    <div id="regFields2" hidden>
+      <label>Phone <span class="opt">optional</span><input id="phone" type="tel" autocomplete="tel" maxlength="40" placeholder="+44 20 …"></label>
+      <label>Telegram username <span class="opt">optional</span><input id="telegram" maxlength="40" placeholder="@yourname"><span class="hint">Your handle in Telegram, under Settings, if you would rather we reach you there than by email.</span></label>
+    </div>
     <label>Password<input id="password" type="password" autocomplete="current-password" minlength="10" required></label>
-    <label id="tenantField" hidden>Tenant id, the name in your log's URL<input id="tenant" placeholder="acme" pattern="[a-z0-9][a-z0-9-]{1,38}[a-z0-9]"></label>
+    <label id="tenantField" hidden>Tenant id<input id="tenant" placeholder="acme" pattern="[a-z0-9][a-z0-9-]{1,38}[a-z0-9]"><span class="hint">A short name for your organisation, filled in from the company name; change it if you like. It becomes the path of your log, which your gateway config and your auditors will use: <code id="tenantPreview">__LOG_BASE__t/&lt;tenant&gt;/</code></span></label>
     <button id="authGo" type="submit">Sign in</button>
     <p class="msg" id="authMsg"></p>
   </form>
   <p class="muted"><button class="link" id="authSwap" type="button">Create an account and a tenant instead</button></p>
   <p class="muted">The free plan is ten thousand appends a month, no card. Your gateway sends only hashes; nothing you log here can be read by us.</p>
 </section>
-<section id="welcome" class="auth" hidden>
+<section id="welcome" class="auth wide" hidden>
   <h1>Your tenant is ready</h1>
+  <p class="muted">Three steps to your first receipt in this log. Everything here is under <b>Setup</b> in the dashboard whenever you need it again.</p>
   <div class="once"><p><b>Your first API key, shown once.</b> Put it in the environment your gateway reads as <code>AGENT_CUSTODY_LOG_TOKEN</code>. We keep only its hash.</p><p class="tok" id="firstToken"></p><button class="quiet" id="copyFirst">Copy key</button></div>
-  <h2>Your welcome sheet</h2>
-  <pre id="firstSheet"></pre>
-  <button id="toDash">Go to the dashboard</button>
+  <div id="firstSetup"></div>
+  <p><button id="toDash">Go to the dashboard</button></p>
 </section>
 <div class="layout" id="app" hidden>
   <nav>
@@ -437,6 +510,7 @@ const PORTAL_PAGE = `<!doctype html>
     <a href="#overview" data-view="overview">Overview</a>
     <a href="#usage" data-view="usage">Usage</a>
     <div class="group">Configure</div>
+    <a href="#setup" data-view="setup">Setup</a>
     <a href="#keys" data-view="keys">API keys <span class="n" id="nKeys"></span></a>
     <a href="#billing" data-view="billing">Billing</a>
     <a href="#export" data-view="export">Export</a>
@@ -480,8 +554,11 @@ const PORTAL_PAGE = `<!doctype html>
       <h1>Export</h1>
       <p class="muted">Everything the log holds about you, any time, with your key: every leaf hash as a log file the verifier reads offline, the signed head, the published keys, the checkpoints, your usage, and the actions taken on your tenant. It checks itself before writing.</p>
       <pre id="exportCmd"></pre>
-      <h2>Welcome sheet</h2>
-      <pre id="sheet"></pre>
+    </div>
+    <div data-pane="setup" hidden>
+      <h1>Setup</h1>
+      <p class="muted">How to connect a gateway or SDK to your log, what to hand your auditors, and how to take your data. The same sheet you saw at registration.</p>
+      <div id="setupPane"></div>
     </div>
   </main>
 </div>
@@ -504,17 +581,39 @@ const PORTAL_PAGE = `<!doctype html>
     for (const a of document.querySelectorAll("nav a[data-view]")) a.classList.toggle("on", a.dataset.view === name);
     location.hash = name;
   };
-  $("authSwap").onclick = () => { registering = !registering; $("authTitle").textContent = registering ? "Create your tenant" : "Sign in"; $("authGo").textContent = registering ? "Create tenant" : "Sign in"; $("tenantField").hidden = !registering; $("tenant").required = registering; $("password").autocomplete = registering ? "new-password" : "current-password"; $("authSwap").textContent = registering ? "I already have an account" : "Create an account and a tenant instead"; };
+  const LOG_BASE = "__LOG_BASE__";
+  const slug = (s) => s.toLowerCase().normalize("NFKD").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40);
+  let tenantEdited = false;
+  const previewTenant = () => { $("tenantPreview").textContent = LOG_BASE + "t/" + ($("tenant").value || "<tenant>") + "/"; };
+  $("company").oninput = () => { if (!tenantEdited) { $("tenant").value = slug($("company").value); previewTenant(); } };
+  $("tenant").oninput = () => { tenantEdited = $("tenant").value !== ""; previewTenant(); };
+  $("authSwap").onclick = () => { registering = !registering; $("authTitle").textContent = registering ? "Create your tenant" : "Sign in"; $("authGo").textContent = registering ? "Create tenant" : "Sign in"; for (const id of ["regFields", "regFields2", "tenantField"]) $(id).hidden = !registering; for (const id of ["name", "company", "tenant"]) $(id).required = registering; $("password").autocomplete = registering ? "new-password" : "current-password"; $("authSwap").textContent = registering ? "I already have an account" : "Create an account and a tenant instead"; previewTenant(); };
   $("authForm").onsubmit = async (e) => {
     e.preventDefault(); $("authMsg").className = "msg"; $("authMsg").textContent = "";
     try {
       if (registering) {
-        const r = await api("POST", "/api/register", { email: $("email").value, password: $("password").value, tenant: $("tenant").value });
-        $("firstToken").textContent = r.token; $("firstSheet").textContent = r.welcome; show("welcome");
+        const r = await api("POST", "/api/register", { email: $("email").value, password: $("password").value, tenant: $("tenant").value, name: $("name").value, company: $("company").value, role: $("role").value, phone: $("phone").value, telegram: $("telegram").value });
+        $("firstToken").textContent = r.token; renderSetup($("firstSetup"), r.setup, true); show("welcome");
       } else { await api("POST", "/api/login", { email: $("email").value, password: $("password").value }); await enter(); }
     } catch (err) { $("authMsg").className = "msg err"; $("authMsg").textContent = err.message; }
   };
   $("copyFirst").onclick = () => navigator.clipboard.writeText($("firstToken").textContent);
+  const snip = (text) => "<div class=snip><pre>" + esc(text) + "</pre><button type=button class=quiet data-copy>Copy</button></div>";
+  const step = (n, title, body) => "<div class=step><span class=n>" + n + "</span><div><h3>" + title + "</h3>" + body + "</div></div>";
+  const renderSetup = (el, s, atRegistration) => {
+    el.innerHTML =
+      step(1, "Keep the key where your gateway runs", (atRegistration ? "<p>The key above is shown once; we keep only its hash. Put it in the environment of the machine that runs your gateway or SDK:</p>" : "<p>Your key was shown once at registration. If it is gone, mint another under <a href=\"#keys\" data-view=\"keys\">API keys</a>. It lives in the environment of the machine that runs your gateway or SDK:</p>") + snip(s.env)) +
+      step(2, "Point your gateway or SDK at your log", "<p>Add this to <code>gateway.json</code> or <code>sdk.json</code>. <code>hashOnly</code> means this log receives the hash of each receipt and never the receipt.</p>" + snip(s.config)) +
+      step(3, "Send the first receipt", "<p>Run your agent through the gateway once. The <a href=\"#overview\" data-view=\"overview\">Overview</a> shows the append within seconds, and the first signed checkpoint follows within minutes. New to the gateway? <a href=\"https://agent-custody.dev/guide/getting-started\">Getting started</a> takes ten minutes.</p>") +
+      step(4, "Hand this to whoever verifies your receipts", "<p>Both commands fetch this log's published keys and pin them; <code>--log-id</code> makes sure the tree heads are this log's.</p>" + snip(s.verify) + snip(s.audit)) +
+      step(5, "Take your data, any time", "<p>Every leaf hash, the signed head, the keys, the checkpoints, your usage, and the actions taken on your tenant, checked against each other and written as a log copy the verifier reads offline.</p>" + snip(s.export)) +
+      "<h2>Your log's addresses</h2><div class=panel><table class=addr><tbody>" + [["Your log", s.log], ["Log id on tree heads", s.logId], ["Your checkpoints", s.checkpoints || "published after your first append"], ["The log's keys", s.keys + (s.keyid ? " (current keyid " + s.keyid.slice(0, 12) + "…)" : "")]].map(([k, v]) => "<tr><th>" + esc(k) + "</th><td class=mono>" + esc(v) + "</td></tr>").join("") + "</tbody></table></div>" +
+      "<h2>What this log does not do</h2><p class=muted>Hold receipt contents; forge a receipt, since your gateway key signs those; or, today, countersign with a second independent witness. <a href=\"https://agent-custody.dev/receipts/#what-a-receipt-proves-and-what-it-does-not\">What a receipt proves and what it does not.</a></p>";
+  };
+  document.addEventListener("click", (e) => {
+    const b = e.target.closest("button[data-copy]"); if (b) { navigator.clipboard.writeText(b.previousElementSibling.textContent).then(() => { b.textContent = "Copied"; setTimeout(() => { b.textContent = "Copy"; }, 1500); }); return; }
+    const a = e.target.closest("a[data-view]"); if (a && a.closest("main")) { e.preventDefault(); view(a.dataset.view); }
+  });
   $("toDash").onclick = () => enter();
   $("signout").onclick = async (e) => { e.preventDefault(); await api("POST", "/api/logout", {}); location.hash = ""; show("auth"); };
   for (const a of document.querySelectorAll("nav a[data-view]")) a.onclick = (e) => { e.preventDefault(); view(a.dataset.view); };
@@ -536,7 +635,7 @@ const PORTAL_PAGE = `<!doctype html>
     $("billingPanel").innerHTML = o.plan === "free"
       ? "<p>You are on the <b>free</b> plan: ten thousand appends a month, no card.</p><p>The <b>team</b> plan is <b>$50 a month</b>: a million appends, email support within two working days, the same export and audit trail. No availability commitment yet, and the design fails closed: when the log is unreachable your gateway withholds pre-committed calls.</p>" + (o.stripe ? "<button id=upgrade>Upgrade to team, $50/month</button>" : "<p class=muted>Card payments are not switched on for this portal yet; email us and we move the plan by hand.</p>")
       : "<p>You are on the <b>" + esc(o.plan) + "</b> plan" + (o.billing ? " (subscription " + esc(o.billing.status) + ")" : "") + ".</p>" + (o.stripe && o.billing ? "<button class=quiet id=manage>Manage billing</button>" : "");
-    $("exportCmd").textContent = o.exportCommand; $("sheet").textContent = o.welcome;
+    $("exportCmd").textContent = o.exportCommand; renderSetup($("setupPane"), o.setup, false);
     const up = $("upgrade"); if (up) up.onclick = async () => { try { const r = await api("POST", "/api/checkout", {}); location.href = r.url; } catch (err) { $("billingMsg").className = "msg err"; $("billingMsg").textContent = err.message; } };
     const mg = $("manage"); if (mg) mg.onclick = async () => { try { const r = await api("POST", "/api/billing-portal", {}); location.href = r.url; } catch (err) { $("billingMsg").className = "msg err"; $("billingMsg").textContent = err.message; } };
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-custody/receipts",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "Chain of custody for AI agents: signed, independently verifiable receipts for tool calls. MCP gateway + Cedar policy + Merkle transparency log",
   "license": "Apache-2.0",
   "repository": {