@lightworkai.official/debug-capture 0.8.3 → 0.9.0

package/README.md

@@ -81,32 +81,41 @@ behind a public key is an endpoint that reads *everyone's* reports.
 
 So your server vouches for your user. Ask the support team for the realm's
 reporter secret (an admin sets `authConfig.reporterSecret` on the realm), keep
-it on your **server**, and mint a short-lived token:
+it on your **server**, and mount one route:
 
 ```ts
-// your backend — e.g. app/api/support-token/route.ts
-import jwt from "jsonwebtoken";
-
-export async function GET() {
-  const user = await currentUser();               // however you authenticate
-  const token = jwt.sign(
-    { sub: user.id, email: user.email, name: user.fullName },
-    process.env.SUPPORT_REPORTER_SECRET!,
-    { algorithm: "HS256", expiresIn: "2m" },
-  );
-  return Response.json({ token });
-}
+// app/api/support-token/route.ts   (Next.js app router)
+import { supportTokenHandler } from "@lightworkai.official/debug-capture/server";
+import { getServerSession } from "next-auth";
+import { authOptions } from "@/lib/auth";
+
+export const dynamic = "force-dynamic";
+export const GET = supportTokenHandler({
+  // The one thing we cannot do for you: only you can read your session.
+  user: async () => {
+    const session = await getServerSession(authOptions);
+    return session?.user?.email ? { id: session.user.id, email: session.user.email } : null;
+  },
+});
 ```
 
+It returns a standard `Response`, so it works anywhere the Fetch API does — Bun,
+Deno, Hono, Next. The secret comes from `SUPPORT_REPORTER_SECRET` unless you
+pass one. `createSupportToken()` is the same thing without the routing, if your
+framework wants the response built its own way.
+
 Wire it once, as the `identity` callback:
 
 ```ts
 configureDebugCapture({
-  host, realmKey, app: { name: "ERP" },
+  host, realmKey, app: { name: "ACME" },
   identity: async () => (await fetch("/api/support-token").then((r) => r.json())).token,
 });
 ```
 
+**Import from `/server`, never the package root** — it uses `node:crypto` and
+touches the secret, while the root export is browser code.
+
 The **secret never reaches the browser** — the callback fetches a finished token
 from your own backend. Returning `null` means "nobody is signed in", and the
 button says so rather than opening a dead link.

package/dist/server.d.ts

@@ -0,0 +1,57 @@
+/** Whoever the host has authenticated. Email is the account key. */
+export interface SupportUser {
+    /** The host's own id for this person, recorded so a changed email still matches. */
+    id?: string | null;
+    email: string;
+    name?: string | null;
+}
+/**
+ * Two minutes.
+ *
+ * The token is fetched when the button is pressed and spent on arrival, so it
+ * only has to survive one redirect — and it travels in a URL, which means
+ * browser history and every access log along the way. The support host refuses
+ * anything older than this regardless of what `exp` claims, so a longer TTL
+ * buys nothing.
+ */
+export declare const DEFAULT_TTL_SECONDS = 120;
+/**
+ * Sign a reporter token for a user the host has ALREADY authenticated.
+ *
+ * Deliberately not a general "sign anything" helper: it asserts the person
+ * handed to it and nothing else. There is no path here to mint a token for
+ * somebody who is not signed in.
+ */
+export declare function createSupportToken(options: {
+    /** The realm's reporter secret. Server-side only — never send it to a browser. */
+    secret: string;
+    user: SupportUser;
+    ttlSeconds?: number;
+}): {
+    token: string;
+    expiresIn: number;
+};
+/**
+ * A ready-made route handler, for the common case.
+ *
+ * Returns a standard `Response`, so it works anywhere the Fetch API does —
+ * Next's app router, Bun, Deno, Hono. The one thing it cannot do for you is
+ * work out who is signed in; that is your session, and only you can read it.
+ *
+ *   // app/api/support-token/route.ts
+ *   import { supportTokenHandler } from "@lightworkai.official/debug-capture/server";
+ *   export const dynamic = "force-dynamic";
+ *   export const GET = supportTokenHandler({
+ *     user: async () => {
+ *       const session = await getServerSession(authOptions);
+ *       return session?.user ? { id: session.user.id, email: session.user.email } : null;
+ *     },
+ *   });
+ */
+export declare function supportTokenHandler(options: {
+    /** Defaults to `process.env.SUPPORT_REPORTER_SECRET`. */
+    secret?: string;
+    /** Null when nobody is signed in — answered 401, which the button reports. */
+    user: () => SupportUser | null | Promise<SupportUser | null>;
+    ttlSeconds?: number;
+}): () => Promise<Response>;

package/dist/server.mjs

@@ -0,0 +1,54 @@
+// src/server.ts
+import { createHmac, randomUUID } from "node:crypto";
+var DEFAULT_TTL_SECONDS = 120;
+var b64 = (value) => Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+function createSupportToken(options) {
+  const email = options.user.email?.trim().toLowerCase();
+  if (!email || !email.includes("@"))
+    throw new Error("createSupportToken: a real email is required");
+  if (!options.secret || options.secret.length < 16) {
+    throw new Error("createSupportToken: the realm's reporter secret is missing or too short");
+  }
+  const now = Math.floor(Date.now() / 1000);
+  const expiresIn = Math.min(Math.max(Math.floor(options.ttlSeconds ?? DEFAULT_TTL_SECONDS), 30), 12 * 60 * 60);
+  const body = `${b64({ alg: "HS256", typ: "JWT" })}.${b64({
+    sub: options.user.id?.trim() || email,
+    email,
+    name: options.user.name?.trim() || null,
+    jti: randomUUID(),
+    iat: now,
+    exp: now + expiresIn
+  })}`;
+  return { token: `${body}.${createHmac("sha256", options.secret).update(body).digest("base64url")}`, expiresIn };
+}
+function supportTokenHandler(options) {
+  return async () => {
+    const secret = options.secret ?? process.env.SUPPORT_REPORTER_SECRET;
+    if (!secret) {
+      return json({ error: "Support identity is not configured" }, 503);
+    }
+    const user = await options.user();
+    if (!user?.email)
+      return json({ error: "Unauthorized" }, 401);
+    try {
+      const { token, expiresIn } = createSupportToken({ secret, user, ttlSeconds: options.ttlSeconds });
+      return json({ token, expiresIn }, 200);
+    } catch {
+      return json({ error: "Support identity is not configured" }, 503);
+    }
+  };
+}
+function json(body, status) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "no-store, private"
+    }
+  });
+}
+export {
+  supportTokenHandler,
+  createSupportToken,
+  DEFAULT_TTL_SECONDS
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightworkai.official/debug-capture",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Report-a-problem widget: rolling network/console/action capture, annotated screenshot, and submission to a Lightwork Support host",
   "type": "module",
   "module": "./dist/index.mjs",
@@ -12,7 +12,12 @@
       "default": "./dist/index.mjs"
     },
     "./embed": "./dist/debug-capture.js",
-    "./style.css": "./src/styles.css"
+    "./style.css": "./src/styles.css",
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.mjs",
+      "default": "./dist/server.mjs"
+    }
   },
   "files": [
     "dist",
@@ -22,7 +27,7 @@
   ],
   "scripts": {
     "build": "rm -rf dist && bun run build:esm && bun run build:iife && bun run build:types",
-    "build:esm": "bun build src/index.ts --outfile dist/index.mjs --format esm --minify",
+    "build:esm": "bun build src/index.ts --outfile dist/index.mjs --format esm --minify && bun build src/server.ts --outfile dist/server.mjs --format esm --target node --external node:crypto",
     "build:iife": "bun build src/embed.ts --outfile dist/debug-capture.js --format iife --minify",
     "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
     "typecheck": "tsc -p tsconfig.json --noEmit",

package/src/server.ts

@@ -0,0 +1,132 @@
+/**
+ * The half that runs on the HOST'S SERVER.
+ *
+ * Reading someone's tickets needs proof of who is asking, and only the host can
+ * give it: the realm key ships in client source, so it can authorise filing a
+ * report and never reading one back. The host signs a short statement of who is
+ * in front of it, with a secret only its server holds.
+ *
+ * That much is unavoidable. What was avoidable is every adopter hand-rolling
+ * HMAC and guessing the claim names — the ERP's version of this file was
+ * eighty-five lines, and getting `alg`, `jti` or `iat` wrong fails in ways that
+ * are hard to read from the outside.
+ *
+ * Imported from "@lightworkai.official/debug-capture/server", NOT from the
+ * package root: this uses node:crypto and must never be reachable from a
+ * browser bundle. It is the one part of this library that touches the secret.
+ */
+import { createHmac, randomUUID } from "node:crypto";
+
+/** Whoever the host has authenticated. Email is the account key. */
+export interface SupportUser {
+  /** The host's own id for this person, recorded so a changed email still matches. */
+  id?: string | null;
+  email: string;
+  name?: string | null;
+}
+
+/**
+ * Two minutes.
+ *
+ * The token is fetched when the button is pressed and spent on arrival, so it
+ * only has to survive one redirect — and it travels in a URL, which means
+ * browser history and every access log along the way. The support host refuses
+ * anything older than this regardless of what `exp` claims, so a longer TTL
+ * buys nothing.
+ */
+export const DEFAULT_TTL_SECONDS = 120;
+
+const b64 = (value: object): string => Buffer.from(JSON.stringify(value), "utf8").toString("base64url");
+
+/**
+ * Sign a reporter token for a user the host has ALREADY authenticated.
+ *
+ * Deliberately not a general "sign anything" helper: it asserts the person
+ * handed to it and nothing else. There is no path here to mint a token for
+ * somebody who is not signed in.
+ */
+export function createSupportToken(options: {
+  /** The realm's reporter secret. Server-side only — never send it to a browser. */
+  secret: string;
+  user: SupportUser;
+  ttlSeconds?: number;
+}): { token: string; expiresIn: number } {
+  const email = options.user.email?.trim().toLowerCase();
+  if (!email || !email.includes("@")) throw new Error("createSupportToken: a real email is required");
+  if (!options.secret || options.secret.length < 16) {
+    throw new Error("createSupportToken: the realm's reporter secret is missing or too short");
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  const expiresIn = Math.min(Math.max(Math.floor(options.ttlSeconds ?? DEFAULT_TTL_SECONDS), 30), 12 * 60 * 60);
+  const body = `${b64({ alg: "HS256", typ: "JWT" })}.${b64({
+    // The host's own id when it has one, so the same person is recognised even
+    // if their email later changes. The email stands in when it does not.
+    sub: options.user.id?.trim() || email,
+    email,
+    name: options.user.name?.trim() || null,
+    // Spent once on arrival; without it the freshness window is a replay window.
+    jti: randomUUID(),
+    iat: now,
+    exp: now + expiresIn,
+  })}`;
+
+  return { token: `${body}.${createHmac("sha256", options.secret).update(body).digest("base64url")}`, expiresIn };
+}
+
+/**
+ * A ready-made route handler, for the common case.
+ *
+ * Returns a standard `Response`, so it works anywhere the Fetch API does —
+ * Next's app router, Bun, Deno, Hono. The one thing it cannot do for you is
+ * work out who is signed in; that is your session, and only you can read it.
+ *
+ *   // app/api/support-token/route.ts
+ *   import { supportTokenHandler } from "@lightworkai.official/debug-capture/server";
+ *   export const dynamic = "force-dynamic";
+ *   export const GET = supportTokenHandler({
+ *     user: async () => {
+ *       const session = await getServerSession(authOptions);
+ *       return session?.user ? { id: session.user.id, email: session.user.email } : null;
+ *     },
+ *   });
+ */
+export function supportTokenHandler(options: {
+  /** Defaults to `process.env.SUPPORT_REPORTER_SECRET`. */
+  secret?: string;
+  /** Null when nobody is signed in — answered 401, which the button reports. */
+  user: () => SupportUser | null | Promise<SupportUser | null>;
+  ttlSeconds?: number;
+}): () => Promise<Response> {
+  return async () => {
+    const secret = options.secret ?? process.env.SUPPORT_REPORTER_SECRET;
+    if (!secret) {
+      // Not something the user did: this deployment was never given a secret.
+      return json({ error: "Support identity is not configured" }, 503);
+    }
+
+    const user = await options.user();
+    if (!user?.email) return json({ error: "Unauthorized" }, 401);
+
+    try {
+      const { token, expiresIn } = createSupportToken({ secret, user, ttlSeconds: options.ttlSeconds });
+      return json({ token, expiresIn }, 200);
+    } catch {
+      // A bad secret or a malformed user is a misconfiguration, not a 401 —
+      // saying "unauthorized" would send someone to check their login.
+      return json({ error: "Support identity is not configured" }, 503);
+    }
+  };
+}
+
+function json(body: unknown, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json",
+      // A bearer credential must not sit in a shared cache, or the next user of
+      // this browser (or a CDN) is handed the last one.
+      "cache-control": "no-store, private",
+    },
+  });
+}

package/src/submit.ts

@@ -100,7 +100,7 @@ export async function submitBundle(title: string, bundle: DebugBundle): Promise<
     description: note.trim() || undefined,
     /*
      * How this application names itself. It becomes the ticket's PREFIX —
-     * `app: { name: "CIB" }` files CIB-100 — so it is the same name on the
+     * `app: { name: "ACME" }` files ACME-100 — so it is the same name on the
      * reporter's list and on the desk's board, whichever realm either of them
      * happens to be looking from.
      */