@guuey/widget-auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loqu, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# @guuey/widget-auth
+
+Mint end-user identity tokens for a [guuey](https://guuey.com) embeddable widget, from your own backend.
+
+Zero runtime dependencies. Node 18+.
+
+```bash
+npm install @guuey/widget-auth
+```
+
+## Why this exists
+
+The widget on your page needs to know **who the visitor is** — otherwise every visit
+starts from scratch, with no history, memory or files. It learns that from a short-lived
+signed token, and only your backend can issue one, because only your backend knows who
+is logged in.
+
+You never hold a signing key. Your app's private key is sealed in the platform's KMS and
+never leaves it; this package is a typed, validated call to the mint route.
+
+## Quick start
+
+**1. Enrol your app once** and keep the secret it prints:
+
+```bash
+guuey widget keys create <appId> --audience <your-app-audience>
+```
+
+The secret is shown **once**. Store it the way you store a database password.
+
+**2. Add a token endpoint to your backend.** This example is a Next.js route handler;
+any framework works the same way.
+
+```ts
+// app/api/guuey-token/route.ts
+import { signUserToken } from "@guuey/widget-auth";
+import { getSession } from "@/lib/auth";
+
+export async function GET() {
+  const session = await getSession();
+  if (!session) return new Response("Unauthorized", { status: 401 });
+
+  const { token } = await signUserToken(
+    { userId: session.userId, name: session.name, email: session.email },
+    {
+      appId: process.env.GUUEY_APP_ID!,
+      appSecret: process.env.GUUEY_APP_SECRET!,
+    }
+  );
+
+  // The widget's `getToken` expects the raw token string.
+  return new Response(token, { headers: { "content-type": "text/plain" } });
+}
+```
+
+**3. Point the widget at it** in the embed snippet:
+
+<!-- GENERATED — do not hand-edit. This block is a paste target, generated by
+     `embedSnippet()` in apps/widget/loader/snippet.ts and byte-asserted against
+     it by that package's snippet-docs-parity.test.ts. Prettier reformatting it
+     (it exploded the queue shim once already) makes it valid JS and a docs lie:
+     the shim must stay byte-identical to the one the loader suite replays. -->
+<!-- prettier-ignore -->
+```html
+<!-- guuey widget. Add this site to the app's allowed domains or the embed is refused. -->
+<script>
+  window.guuey = window.guuey || function(){(guuey.q=guuey.q||[]).push(arguments)};
+  guuey("init", {
+    app: "app_abc123",
+    identity: {
+      getToken: (reason) =>
+        fetch("/api/guuey-token" + "?reason=" + reason).then((r) => {
+          if (!r.ok) throw new Error("token endpoint failed: " + r.status);
+          return r.text();
+        }),
+    },
+  });
+</script>
+<script src="https://widget.guuey.com/v1.js" async></script>
+```
+
+Your endpoint is called by the browser; the app secret stays on your server.
+
+## The app secret is server-side only
+
+`appSecret` authorizes minting an identity for **any user of your app**. If it reaches a
+browser — bundled into frontend code, or because you called this package from the client —
+anyone who reads it can impersonate any of your users.
+
+That is the whole reason the widget asks _your_ server for a token instead of minting one
+itself. Keep the secret in an environment variable on the server, and never return it from
+an endpoint.
+
+**`signUserToken` refuses to run in a browser** — it throws a `WidgetAuthConfigError` if it
+detects a DOM, before doing anything else — so this fails loudly at your first call rather
+than silently shipping the secret to every visitor. Edge runtimes (Cloudflare Workers,
+Vercel Edge, Deno Deploy) are not browsers and are fine.
+
+If it does leak, rotate it:
+
+```bash
+guuey widget keys rotate <appId> --new-secret
+```
+
+## Caching tokens
+
+Tokens are short-lived (15 minutes by default). Minting one per page load is fine, but if
+your token endpoint is hot you can cache.
+
+**Cache per user, and expire ~2 minutes before the token does.** The margin covers the
+round trip plus any clock difference between your server and the visitor's browser.
+
+```ts
+const cache = new Map<string, { token: string; refreshAt: number }>();
+const MARGIN_SECONDS = 120;
+
+async function tokenFor(user: { userId: string; name?: string }, force: boolean) {
+  const hit = cache.get(user.userId);
+  if (!force && hit && Date.now() / 1000 < hit.refreshAt) return hit.token;
+
+  const { token, expiresAtEpoch } = await signUserToken(user, {
+    appId: process.env.GUUEY_APP_ID!,
+    appSecret: process.env.GUUEY_APP_SECRET!,
+  });
+  cache.set(user.userId, { token, refreshAt: expiresAtEpoch - MARGIN_SECONDS });
+  return token;
+}
+```
+
+**If you cache, you must honour `reason`.** The widget calls `getToken(reason)` with:
+
+| `reason`    | Meaning                                                                       |
+| ----------- | ----------------------------------------------------------------------------- |
+| `'initial'` | First token needed for this session — a cached token is fine.                 |
+| `'expired'` | The token was rejected as expired. **Mint a fresh one, ignoring your cache.** |
+
+A cache that ignores `'expired'` keeps returning the same dead token, and every turn after
+the first expiry fails. Forward the reason to your endpoint and pass it through:
+
+```ts
+export async function GET(request: Request) {
+  const session = await getSession();
+  if (!session) return new Response("Unauthorized", { status: 401 });
+
+  const reason = new URL(request.url).searchParams.get("reason");
+  const token = await tokenFor(session, reason === "expired");
+  return new Response(token, { headers: { "content-type": "text/plain" } });
+}
+```
+
+## Errors
+
+Every failure throws a subclass of `WidgetAuthError` — never a partial result, and never a
+token-shaped value. A service that returns a 500, an HTML error page, or a 200 with an
+unusable body all raise an error rather than producing a token nobody issued.
+
+| Class                             | Cause                                                                                                                                                                       | Retry?                        |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `WidgetAuthConfigError`           | Running in a browser (see above), or bad arguments — missing `appId`/`appSecret`/base URL, over-long field, `ttlSeconds` outside `1..3600`. Thrown before any network call. | No                            |
+| `WidgetAuthCredentialError`       | HTTP 401. The secret is wrong, revoked, or for another app.                                                                                                                 | No                            |
+| `WidgetAuthAppNotConfiguredError` | HTTP 409. The app isn't wired to its own widget issuer; the message names the fixing command.                                                                               | No                            |
+| `WidgetAuthRequestError`          | HTTP 400. Usually means this package is out of date with the deployed API.                                                                                                  | No                            |
+| `WidgetAuthServiceError`          | 5xx, an unexpected status, or an unusable response body.                                                                                                                    | `retryable` is `true` for 5xx |
+| `WidgetAuthNetworkError`          | The request never arrived — DNS, TLS, timeout, abort. Original error on `cause`.                                                                                            | Yes                           |
+
+Each carries `status` (when there was one) and `retryable`:
+
+```ts
+try {
+  await signUserToken(user, config);
+} catch (err) {
+  if (err instanceof WidgetAuthError && err.retryable) {
+    // transient — back off and try again
+  }
+  throw err;
+}
+```
+
+A 401 does not tell you _which_ of "wrong secret", "revoked key" or "app not enrolled" it
+was. That is deliberate: the app id is caller-supplied, so a more specific answer would let
+anyone probe which apps exist.
+
+**The app secret is kept out of every error this package constructs** — its message, its
+stack, and `JSON.stringify(err)`. Any text sourced from the service or from a transport
+error is redacted first, and `cause` is non-enumerable so a structured logger cannot drag
+a transport error's request dump into a log line.
+
+One gap worth knowing, because it is outside what this package controls:
+`console.error(err)` in Node prints the **cause chain** via `util.inspect`, which reaches
+the non-enumerable `cause`. If your `fetch` implementation puts the secret in its own
+error's message, that text is not redacted. Log `err.message` rather than `err` if your
+aggregator ingests raw error objects.
+
+## What the platform sets, and you must not
+
+The token's claims are assembled **server-side**. Do not re-implement any of this:
+
+- **`iat` and `nbf` are backdated 60 seconds.** The agent verifies with zero clock
+  tolerance, so this absorbs ordinary drift. `exp` is measured from the real current time,
+  not from the backdated `iat`, so the headroom costs no usable life. Backdating again on
+  top of it would not shorten anything — it would widen the acceptance window, so the
+  60-second skew margin quietly stops meaning 60 seconds, and `iat` would misstate the
+  token's age to anything that reads it.
+- **`exp`** defaults to 15 minutes; `ttlSeconds` may set `1..3600`. Shorter is safer — the
+  token is a bearer credential held in a browser, and the widget re-requests one when it
+  expires. It is not a session length.
+- **`iss`** is your app's canonical issuer, and **`aud`** is your app's configured audience.
+
+Attempting to send any of them is rejected by the signer outright.
+
+## API
+
+### `signUserToken(user, config): Promise<WidgetToken>`
+
+**`user`**
+
+| Field    | Type     |                                                                        |
+| -------- | -------- | ---------------------------------------------------------------------- |
+| `userId` | `string` | **Required.** Your stable id for this user; becomes the token's `sub`. |
+| `name`   | `string` | Optional. Display name.                                                |
+| `email`  | `string` | Optional.                                                              |
+
+`userId` must be **stable for the life of the account** — it is what ties a returning
+visitor to their existing conversations, memory and files. A value that changes (a session
+id, an editable email) silently orphans all of it and the user reappears as a stranger.
+
+**`config`**
+
+| Field        | Type          |                                                                                             |
+| ------------ | ------------- | ------------------------------------------------------------------------------------------- |
+| `appId`      | `string`      | **Required.**                                                                               |
+| `appSecret`  | `string`      | **Required.** Server-side only.                                                             |
+| `apiBaseUrl` | `string`      | Defaults to `GUUEY_API_URL`. No compiled-in default — the API base differs per environment. |
+| `ttlSeconds` | `number`      | `1..3600`. Defaults to the service's 15 minutes.                                            |
+| `signal`     | `AbortSignal` | Aborts the request.                                                                         |
+| `fetch`      | `FetchLike`   | Override the HTTP client. For tests.                                                        |
+
+**Returns `WidgetToken`**
+
+| Field            | Type     |                                                 |
+| ---------------- | -------- | ----------------------------------------------- |
+| `token`          | `string` | The signed JWT to hand to the widget.           |
+| `expiresAtEpoch` | `number` | Unix epoch seconds. Use it to drive your cache. |
+| `issuer`         | `string` | The issuer that signed it.                      |
+| `kid`            | `string` | The signing key's id.                           |
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,157 @@
+/**
+ * The error taxonomy for `@guuey/widget-auth`.
+ *
+ * Every failure is one of these, and every one of them is a subclass of
+ * {@link WidgetAuthError} — so a caller that only wants "did minting fail?" needs
+ * one `catch` clause, while a caller that wants to react differently to a bad
+ * secret than to a transient outage can switch on the class.
+ *
+ * ## Two invariants this file exists to hold
+ *
+ * **1. A failure is never a token.** Every path here throws. There is no
+ * "degraded" return value, no empty-string token, no partially-populated result:
+ * a token handed to a browser is a bearer credential, and one minted from a
+ * misread 500 response would be a credential nobody issued.
+ *
+ * **2. The app secret never reaches an error.** It is a server-side credential
+ * whose entire value is that it exists in exactly one place, and an exception is
+ * the most likely way for it to escape into a log aggregator. Errors therefore
+ * carry only a status, a retryability flag and a message — and any message
+ * sourced from outside this package (the service's response, a transport
+ * error's text) is passed through {@link redactSecret} first, so the property
+ * holds structurally rather than by trusting the other end.
+ *
+ * `cause` is attached with the `Error` options form deliberately: that makes it
+ * non-enumerable, so a structured logger serializing the error cannot drag a
+ * transport error's request dump — headers included — into the log line.
+ *
+ * **The honest bound on that claim.** It covers what this package constructs:
+ * the message, the stack, and `JSON.stringify`. It does NOT cover
+ * `console.error(err)`, which in Node prints the cause chain through
+ * `util.inspect` and reaches the non-enumerable `cause` — so a `fetch`
+ * implementation that puts the secret in its OWN error's message escapes
+ * redaction by that path. Closing it means wrapping the cause in a redacted
+ * copy, which costs the caller the original error object (`cause.code`,
+ * `instanceof`); that trade is worth making deliberately rather than as a side
+ * effect, so it is documented here and in the README instead of half-done.
+ */
+/** What a caller may do about a failure, without parsing messages. */
+export declare abstract class WidgetAuthError extends Error {
+    /**
+     * The HTTP status the token service returned, or `undefined` when the request
+     * never got that far (bad configuration, a transport failure).
+     */
+    readonly status: number | undefined;
+    /**
+     * Whether retrying the SAME call with backoff could plausibly succeed.
+     *
+     * `false` for anything the caller must change first — a wrong secret, an app
+     * that is not wired to its issuer, a malformed request. Retrying those just
+     * burns the shared rate-limit bucket.
+     */
+    readonly retryable: boolean;
+    protected constructor(message: string, retryable: boolean, status?: number, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The call was wrong before it was ever sent — a missing or malformed `appId`,
+ * `appSecret`, `apiBaseUrl`, `userId`, or a `ttlSeconds` outside `1..3600`.
+ *
+ * Thrown before any network call, so a configuration mistake costs nothing and
+ * cannot be mistaken for a service outage.
+ */
+export declare class WidgetAuthConfigError extends WidgetAuthError {
+    constructor(message: string);
+}
+/**
+ * HTTP 401 — the app secret was not accepted.
+ *
+ * **Deliberately indistinguishable**: a wrong secret, a revoked key and an app
+ * that was never enrolled all produce this one error, because the `appId` is
+ * caller-supplied and anything finer would turn the route into an oracle for
+ * which apps exist. So "which of the three is it?" is a question this error
+ * cannot answer by design — check the secret first, then the key's status with
+ * `guuey widget keys`.
+ */
+export declare class WidgetAuthCredentialError extends WidgetAuthError {
+    constructor(message: string, status: number);
+}
+/**
+ * HTTP 409 — the secret was accepted, but the app is not wired to its own widget
+ * issuer, so a token minted here would be rejected by the app that received it.
+ *
+ * The message names the command that repairs it. A correctly-onboarded app never
+ * reaches this: `guuey widget keys create --audience` wires the binding in the
+ * same ceremony that mints the secret.
+ */
+export declare class WidgetAuthAppNotConfiguredError extends WidgetAuthError {
+    constructor(message: string, status: number);
+}
+/**
+ * HTTP 400 — the token service rejected the request body.
+ *
+ * This package validates every field the service validates, so in normal use
+ * this is unreachable; seeing it means either a version skew between this
+ * package and the deployed service, or a bug here. Either way it is not
+ * something a retry fixes.
+ */
+export declare class WidgetAuthRequestError extends WidgetAuthError {
+    constructor(message: string, status: number);
+}
+/**
+ * The service failed, or answered with something this package cannot use — a
+ * 5xx, an unexpected status, a body that is not JSON, or a 200 whose shape is
+ * not a minted token.
+ *
+ * `retryable` is `true` only for 5xx. A 200 with an unusable body is NOT
+ * retryable: the request succeeded and the answer was wrong, which a retry
+ * reproduces.
+ */
+export declare class WidgetAuthServiceError extends WidgetAuthError {
+    constructor(message: string, status: number | undefined, retryable: boolean, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The request never reached the token service — DNS, TCP, TLS, a timeout, or an
+ * aborted `AbortSignal`.
+ *
+ * The underlying error is attached as `cause` (non-enumerable, so it does not
+ * land in a serialized log line) and its text is redacted into the message.
+ */
+export declare class WidgetAuthNetworkError extends WidgetAuthError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+        retryable?: boolean;
+    });
+}
+/**
+ * Was this transport failure the CALLER cancelling the request?
+ *
+ * A caller-initiated abort is the one transport failure that must not be
+ * `retryable`: the integrator asked for this mint to stop, and a retry loop
+ * keyed on `retryable` would re-issue the very call they abandoned — spending
+ * a mint (and a rate-limit slot) against their own intent. Everything else
+ * here — DNS, TCP, TLS, a timeout — genuinely may succeed on a second try.
+ *
+ * Detected structurally rather than by message text: the DOM standard's
+ * `AbortError` name is what `fetch` rejects with on `signal.abort()`, and
+ * undici/Node use the same name.
+ */
+export declare function isAbortError(err: unknown): boolean;
+/**
+ * Replace every occurrence of the app secret with `[redacted]`.
+ *
+ * Applied to every string that enters an error message from outside this
+ * package. The token service never echoes the secret and a transport error
+ * usually does not either — but "usually" is not a security property, and
+ * `fetch` implementations that quote the failing request with its headers do
+ * exist. One cheap pass makes the guarantee structural.
+ *
+ * A short or empty secret is ignored rather than replaced: redacting a 1-char
+ * string would corrupt the message without protecting anything, and only a
+ * well-formed secret is long enough to be worth hiding.
+ */
+export declare function redactSecret(text: string, secret: string): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,sEAAsE;AACtE,8BAAsB,eAAgB,SAAQ,KAAK;IACjD;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAEpC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B,SAAS,aACP,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,OAAO,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAOhC;AAED;;;;;;GAMG;AACH,qBAAa,qBAAsB,SAAQ,eAAe;gBAC5C,OAAO,EAAE,MAAM;CAG5B;AAED;;;;;;;;;GASG;AACH,qBAAa,yBAA0B,SAAQ,eAAe;gBAChD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAG5C;AAED;;;;;;;GAOG;AACH,qBAAa,+BAAgC,SAAQ,eAAe;gBACtD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAG5C;AAED;;;;;;;GAOG;AACH,qBAAa,sBAAuB,SAAQ,eAAe;gBAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAG5C;AAED;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,SAAQ,eAAe;gBAEvD,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,SAAS,EAAE,OAAO,EAClB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAIhC;AAED;;;;;;GAMG;AACH,qBAAa,sBAAuB,SAAQ,eAAe;gBAC7C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE;CAGhF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAOlD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGjE"}

package/dist/errors.js

@@ -0,0 +1,175 @@
+/**
+ * The error taxonomy for `@guuey/widget-auth`.
+ *
+ * Every failure is one of these, and every one of them is a subclass of
+ * {@link WidgetAuthError} — so a caller that only wants "did minting fail?" needs
+ * one `catch` clause, while a caller that wants to react differently to a bad
+ * secret than to a transient outage can switch on the class.
+ *
+ * ## Two invariants this file exists to hold
+ *
+ * **1. A failure is never a token.** Every path here throws. There is no
+ * "degraded" return value, no empty-string token, no partially-populated result:
+ * a token handed to a browser is a bearer credential, and one minted from a
+ * misread 500 response would be a credential nobody issued.
+ *
+ * **2. The app secret never reaches an error.** It is a server-side credential
+ * whose entire value is that it exists in exactly one place, and an exception is
+ * the most likely way for it to escape into a log aggregator. Errors therefore
+ * carry only a status, a retryability flag and a message — and any message
+ * sourced from outside this package (the service's response, a transport
+ * error's text) is passed through {@link redactSecret} first, so the property
+ * holds structurally rather than by trusting the other end.
+ *
+ * `cause` is attached with the `Error` options form deliberately: that makes it
+ * non-enumerable, so a structured logger serializing the error cannot drag a
+ * transport error's request dump — headers included — into the log line.
+ *
+ * **The honest bound on that claim.** It covers what this package constructs:
+ * the message, the stack, and `JSON.stringify`. It does NOT cover
+ * `console.error(err)`, which in Node prints the cause chain through
+ * `util.inspect` and reaches the non-enumerable `cause` — so a `fetch`
+ * implementation that puts the secret in its OWN error's message escapes
+ * redaction by that path. Closing it means wrapping the cause in a redacted
+ * copy, which costs the caller the original error object (`cause.code`,
+ * `instanceof`); that trade is worth making deliberately rather than as a side
+ * effect, so it is documented here and in the README instead of half-done.
+ */
+/** What a caller may do about a failure, without parsing messages. */
+export class WidgetAuthError extends Error {
+    /**
+     * The HTTP status the token service returned, or `undefined` when the request
+     * never got that far (bad configuration, a transport failure).
+     */
+    status;
+    /**
+     * Whether retrying the SAME call with backoff could plausibly succeed.
+     *
+     * `false` for anything the caller must change first — a wrong secret, an app
+     * that is not wired to its issuer, a malformed request. Retrying those just
+     * burns the shared rate-limit bucket.
+     */
+    retryable;
+    constructor(message, retryable, status, options) {
+        super(message, options);
+        this.name = new.target.name;
+        this.retryable = retryable;
+        this.status = status;
+    }
+}
+/**
+ * The call was wrong before it was ever sent — a missing or malformed `appId`,
+ * `appSecret`, `apiBaseUrl`, `userId`, or a `ttlSeconds` outside `1..3600`.
+ *
+ * Thrown before any network call, so a configuration mistake costs nothing and
+ * cannot be mistaken for a service outage.
+ */
+export class WidgetAuthConfigError extends WidgetAuthError {
+    constructor(message) {
+        super(message, false);
+    }
+}
+/**
+ * HTTP 401 — the app secret was not accepted.
+ *
+ * **Deliberately indistinguishable**: a wrong secret, a revoked key and an app
+ * that was never enrolled all produce this one error, because the `appId` is
+ * caller-supplied and anything finer would turn the route into an oracle for
+ * which apps exist. So "which of the three is it?" is a question this error
+ * cannot answer by design — check the secret first, then the key's status with
+ * `guuey widget keys`.
+ */
+export class WidgetAuthCredentialError extends WidgetAuthError {
+    constructor(message, status) {
+        super(message, false, status);
+    }
+}
+/**
+ * HTTP 409 — the secret was accepted, but the app is not wired to its own widget
+ * issuer, so a token minted here would be rejected by the app that received it.
+ *
+ * The message names the command that repairs it. A correctly-onboarded app never
+ * reaches this: `guuey widget keys create --audience` wires the binding in the
+ * same ceremony that mints the secret.
+ */
+export class WidgetAuthAppNotConfiguredError extends WidgetAuthError {
+    constructor(message, status) {
+        super(message, false, status);
+    }
+}
+/**
+ * HTTP 400 — the token service rejected the request body.
+ *
+ * This package validates every field the service validates, so in normal use
+ * this is unreachable; seeing it means either a version skew between this
+ * package and the deployed service, or a bug here. Either way it is not
+ * something a retry fixes.
+ */
+export class WidgetAuthRequestError extends WidgetAuthError {
+    constructor(message, status) {
+        super(message, false, status);
+    }
+}
+/**
+ * The service failed, or answered with something this package cannot use — a
+ * 5xx, an unexpected status, a body that is not JSON, or a 200 whose shape is
+ * not a minted token.
+ *
+ * `retryable` is `true` only for 5xx. A 200 with an unusable body is NOT
+ * retryable: the request succeeded and the answer was wrong, which a retry
+ * reproduces.
+ */
+export class WidgetAuthServiceError extends WidgetAuthError {
+    constructor(message, status, retryable, options) {
+        super(message, retryable, status, options);
+    }
+}
+/**
+ * The request never reached the token service — DNS, TCP, TLS, a timeout, or an
+ * aborted `AbortSignal`.
+ *
+ * The underlying error is attached as `cause` (non-enumerable, so it does not
+ * land in a serialized log line) and its text is redacted into the message.
+ */
+export class WidgetAuthNetworkError extends WidgetAuthError {
+    constructor(message, options) {
+        super(message, options?.retryable ?? true, undefined, options);
+    }
+}
+/**
+ * Was this transport failure the CALLER cancelling the request?
+ *
+ * A caller-initiated abort is the one transport failure that must not be
+ * `retryable`: the integrator asked for this mint to stop, and a retry loop
+ * keyed on `retryable` would re-issue the very call they abandoned — spending
+ * a mint (and a rate-limit slot) against their own intent. Everything else
+ * here — DNS, TCP, TLS, a timeout — genuinely may succeed on a second try.
+ *
+ * Detected structurally rather than by message text: the DOM standard's
+ * `AbortError` name is what `fetch` rejects with on `signal.abort()`, and
+ * undici/Node use the same name.
+ */
+export function isAbortError(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'name' in err &&
+        err.name === 'AbortError');
+}
+/**
+ * Replace every occurrence of the app secret with `[redacted]`.
+ *
+ * Applied to every string that enters an error message from outside this
+ * package. The token service never echoes the secret and a transport error
+ * usually does not either — but "usually" is not a security property, and
+ * `fetch` implementations that quote the failing request with its headers do
+ * exist. One cheap pass makes the guarantee structural.
+ *
+ * A short or empty secret is ignored rather than replaced: redacting a 1-char
+ * string would corrupt the message without protecting anything, and only a
+ * well-formed secret is long enough to be worth hiding.
+ */
+export function redactSecret(text, secret) {
+    if (secret.length < 8)
+        return text;
+    return text.split(secret).join('[redacted]');
+}

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * `@guuey/widget-auth` — mint end-user identity tokens for a guuey embeddable
+ * widget, from your own backend.
+ *
+ * ```ts
+ * import { signUserToken } from '@guuey/widget-auth';
+ *
+ * const { token, expiresAtEpoch } = await signUserToken(
+ *   { userId: user.id, name: user.name, email: user.email },
+ *   { appId: process.env.GUUEY_APP_ID!, appSecret: process.env.GUUEY_APP_SECRET! },
+ * );
+ * ```
+ *
+ * ## What this package does NOT do, and why that matters
+ *
+ * It holds no key material and assembles no claims. The app's RSA private key
+ * lives sealed in the platform's KMS and never leaves it, so this package is a
+ * typed, validated HTTP call to the mint route and nothing more.
+ *
+ * In particular, **the token's time claims are assembled server-side and this
+ * package must never re-implement them.** The signer sets `iat` and `nbf`
+ * backdated 60 seconds — absorbing ordinary clock drift between the signer and
+ * the agent pod, which verifies with zero clock tolerance — and derives `exp`
+ * from the real current time, so the backdating buys verification headroom
+ * without shortening the token's usable life. It also sets `iss` from the app's
+ * canonical issuer string and `aud` from the app's own configuration. Sending
+ * any of those from here is rejected outright by the signer's strict claim
+ * parser, which allowlists exactly `sub`, `name` and `email` — so the rule is
+ * enforced by the other end rather than merely stated here.
+ *
+ * Were the backdate re-implemented here anyway, the damage would not be a
+ * shorter token: `exp` does not move, so nothing expires sooner. It would WIDEN
+ * the acceptance window — `nbf` slides another 60s into the past, so the
+ * skew margin silently stops being the 60 seconds it is documented as — and
+ * `iat` would misstate the token's age to every consumer that reads it.
+ *
+ * ## The app secret is a SERVER-side credential
+ *
+ * `appSecret` authorizes minting an identity for *any* user of your app. It must
+ * live only on your backend. If it reaches a browser — bundled into frontend
+ * code, or because this package was called from the client — anyone who reads it
+ * can mint a token for any of your users, which is the entire threat model this
+ * design exists to prevent. That is why the widget asks *your* server for a
+ * token rather than minting one itself.
+ */
+import { WidgetAuthAppNotConfiguredError, WidgetAuthConfigError, WidgetAuthCredentialError, WidgetAuthError, WidgetAuthNetworkError, WidgetAuthRequestError, WidgetAuthServiceError } from './errors.js';
+export { WidgetAuthAppNotConfiguredError, WidgetAuthConfigError, WidgetAuthCredentialError, WidgetAuthError, WidgetAuthNetworkError, WidgetAuthRequestError, WidgetAuthServiceError, };
+/** The end-user a token is being minted for. */
+export interface WidgetUser {
+    /**
+     * Your stable identifier for this user — it becomes the token's `sub`, and the
+     * platform derives the user's durable widget identity from it.
+     *
+     * It must be stable for the life of the account: it is what ties a returning
+     * visitor to their existing conversations, memory and files. A value that
+     * changes (a session id, an email that can be edited) silently orphans all of
+     * it and the user reappears as a stranger.
+     */
+    userId: string;
+    /** Display name, shown in the widget. Optional. */
+    name?: string;
+    /** Email, available to the agent. Optional. */
+    email?: string;
+}
+/** Where to mint, and as whom. */
+export interface WidgetAuthConfig {
+    /** The guuey app this token is for. */
+    appId: string;
+    /**
+     * The app secret from `guuey widget keys create`. **Server-side only** — see
+     * the module docblock.
+     */
+    appSecret: string;
+    /**
+     * The guuey API base URL, e.g. `https://api.guuey.com`. Falls back to the
+     * `GUUEY_API_URL` environment variable.
+     *
+     * There is deliberately no compiled-in default: the API base differs per
+     * environment, and a wrong built-in default would fail in a way that looks
+     * like a credential problem rather than a configuration one.
+     */
+    apiBaseUrl?: string;
+    /**
+     * Token lifetime in seconds, `1..3600`. Defaults to the service's 15 minutes.
+     *
+     * Shorter is safer — the token is a bearer credential held in a browser, and
+     * the widget re-requests one from you when it expires. Prefer the default over
+     * a long TTL; it is not a session length.
+     */
+    ttlSeconds?: number;
+    /** Aborts the request. */
+    signal?: AbortSignal;
+    /** Override the HTTP client. Intended for tests. */
+    fetch?: FetchLike;
+}
+/** A minted token, exactly as the mint route returns it. */
+export interface WidgetToken {
+    /** The signed JWT to hand to the widget. */
+    token: string;
+    /** Unix epoch seconds at which `token` stops verifying. */
+    expiresAtEpoch: number;
+    /** The issuer that signed it. */
+    issuer: string;
+    /** The signing key's id. */
+    kid: string;
+}
+/** The request shape this package sends. */
+export interface WidgetAuthRequestInit {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}
+/** The part of a `fetch` response this package reads. */
+export interface WidgetAuthFetchResponse {
+    status: number;
+    json(): Promise<unknown>;
+}
+/**
+ * The HTTP seam. Structurally satisfied by the global `fetch`, so overriding it
+ * is only needed in tests.
+ */
+export type FetchLike = (url: string, init: WidgetAuthRequestInit) => Promise<WidgetAuthFetchResponse>;
+/**
+ * Mint an end-user token for your widget.
+ *
+ * Resolves with a {@link WidgetToken}, or **throws** — always a
+ * {@link WidgetAuthError} subclass, never a partially-formed result. See
+ * `errors.ts` for the taxonomy and which failures a retry can fix.
+ *
+ * @param user   the end-user this token identifies
+ * @param config the app, its secret, and where to mint
+ */
+export declare function signUserToken(user: WidgetUser, config: WidgetAuthConfig): Promise<WidgetToken>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,OAAO,EAGL,+BAA+B,EAC/B,qBAAqB,EACrB,yBAAyB,EACzB,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,+BAA+B,EAC/B,qBAAqB,EACrB,yBAAyB,EACzB,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,sBAAsB,GACvB,CAAC;AA4BF,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB;;;;;;;;OAQG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,kCAAkC;AAClC,MAAM,WAAW,gBAAgB;IAC/B,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,oDAAoD;IACpD,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;IACvB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;CACb;AAED,4CAA4C;AAC5C,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,yDAAyD;AACzD,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,qBAAqB,KACxB,OAAO,CAAC,uBAAuB,CAAC,CAAC;AAWtC;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,WAAW,CAAC,CAmEtB"}

package/dist/index.js

@@ -0,0 +1,324 @@
+/**
+ * `@guuey/widget-auth` — mint end-user identity tokens for a guuey embeddable
+ * widget, from your own backend.
+ *
+ * ```ts
+ * import { signUserToken } from '@guuey/widget-auth';
+ *
+ * const { token, expiresAtEpoch } = await signUserToken(
+ *   { userId: user.id, name: user.name, email: user.email },
+ *   { appId: process.env.GUUEY_APP_ID!, appSecret: process.env.GUUEY_APP_SECRET! },
+ * );
+ * ```
+ *
+ * ## What this package does NOT do, and why that matters
+ *
+ * It holds no key material and assembles no claims. The app's RSA private key
+ * lives sealed in the platform's KMS and never leaves it, so this package is a
+ * typed, validated HTTP call to the mint route and nothing more.
+ *
+ * In particular, **the token's time claims are assembled server-side and this
+ * package must never re-implement them.** The signer sets `iat` and `nbf`
+ * backdated 60 seconds — absorbing ordinary clock drift between the signer and
+ * the agent pod, which verifies with zero clock tolerance — and derives `exp`
+ * from the real current time, so the backdating buys verification headroom
+ * without shortening the token's usable life. It also sets `iss` from the app's
+ * canonical issuer string and `aud` from the app's own configuration. Sending
+ * any of those from here is rejected outright by the signer's strict claim
+ * parser, which allowlists exactly `sub`, `name` and `email` — so the rule is
+ * enforced by the other end rather than merely stated here.
+ *
+ * Were the backdate re-implemented here anyway, the damage would not be a
+ * shorter token: `exp` does not move, so nothing expires sooner. It would WIDEN
+ * the acceptance window — `nbf` slides another 60s into the past, so the
+ * skew margin silently stops being the 60 seconds it is documented as — and
+ * `iat` would misstate the token's age to every consumer that reads it.
+ *
+ * ## The app secret is a SERVER-side credential
+ *
+ * `appSecret` authorizes minting an identity for *any* user of your app. It must
+ * live only on your backend. If it reaches a browser — bundled into frontend
+ * code, or because this package was called from the client — anyone who reads it
+ * can mint a token for any of your users, which is the entire threat model this
+ * design exists to prevent. That is why the widget asks *your* server for a
+ * token rather than minting one itself.
+ */
+import { isAbortError, redactSecret, WidgetAuthAppNotConfiguredError, WidgetAuthConfigError, WidgetAuthCredentialError, WidgetAuthError, WidgetAuthNetworkError, WidgetAuthRequestError, WidgetAuthServiceError, } from './errors.js';
+export { WidgetAuthAppNotConfiguredError, WidgetAuthConfigError, WidgetAuthCredentialError, WidgetAuthError, WidgetAuthNetworkError, WidgetAuthRequestError, WidgetAuthServiceError, };
+/** The credential family the mint route accepts. */
+const SECRET_PREFIX = 'guuey_widget_';
+/** The mint route's path, appended to the resolved API base URL. */
+const MINT_PATH = '/v1/widget/token';
+/**
+ * Field caps, mirroring the token service's own.
+ *
+ * They exist server-side because KMS refuses to sign a message over 4096 bytes
+ * and these fields are caller-controlled. Mirroring them here turns a round trip
+ * that ends in a 400 into an immediate, local error naming the field — and the
+ * service still enforces them, so a skew between this package and a newer
+ * deployment fails safe rather than silently.
+ */
+const MAX_USER_ID_LENGTH = 256;
+const MAX_NAME_LENGTH = 256;
+const MAX_EMAIL_LENGTH = 320;
+/** TTL bounds, mirroring the service. The default (900s) is the service's. */
+const MIN_TTL_SECONDS = 1;
+const MAX_TTL_SECONDS = 3600;
+/** How much of a service-supplied message to keep in an error. */
+const MAX_SERVICE_MESSAGE_LENGTH = 400;
+/**
+ * Mint an end-user token for your widget.
+ *
+ * Resolves with a {@link WidgetToken}, or **throws** — always a
+ * {@link WidgetAuthError} subclass, never a partially-formed result. See
+ * `errors.ts` for the taxonomy and which failures a retry can fix.
+ *
+ * @param user   the end-user this token identifies
+ * @param config the app, its secret, and where to mint
+ */
+export async function signUserToken(user, config) {
+    // FIRST, before any other check. Running in a browser is not one
+    // misconfiguration among several — it means the secret is already in a
+    // shipped bundle, and saying "appId is required" to someone in that position
+    // would be answering the wrong question.
+    assertNotBrowser();
+    const { appId, appSecret } = config;
+    // Validate everything before touching the network: a configuration mistake
+    // should cost nothing, name its own field, and never be confusable with an
+    // outage or a rejected credential.
+    requireNonEmpty(appId, 'appId');
+    requireNonEmpty(appSecret, 'appSecret');
+    if (!appSecret.startsWith(SECRET_PREFIX)) {
+        // Checked locally so a credential from another family is never transmitted
+        // at all — and because the service's answer would be the deliberately
+        // uninformative 401, which would send the reader hunting for the wrong bug.
+        throw new WidgetAuthConfigError(`appSecret does not look like a widget app secret (expected it to start with "${SECRET_PREFIX}"). ` +
+            'Widget secrets come from `guuey widget keys create <appId>`; a personal access token or ' +
+            'workspace API key will not work on this route.');
+    }
+    const baseUrl = resolveBaseUrl(config.apiBaseUrl);
+    const body = buildBody(appId, user, config.ttlSeconds);
+    const doFetch = resolveFetch(config.fetch);
+    const init = {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${appSecret}`,
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify(body),
+    };
+    if (config.signal !== undefined)
+        init.signal = config.signal;
+    let response;
+    try {
+        response = await doFetch(`${baseUrl}${MINT_PATH}`, init);
+    }
+    catch (err) {
+        // A caller-initiated abort is NOT retryable — see `isAbortError`.
+        const aborted = isAbortError(err);
+        throw new WidgetAuthNetworkError(aborted
+            ? `The mint request to ${baseUrl} was aborted by the caller.`
+            : `Could not reach the guuey token service at ${baseUrl}: ${describe(err, appSecret)}`, { cause: err, retryable: !aborted });
+    }
+    // A body that is not JSON is a fact about the response, not an exception:
+    // a proxy's HTML error page is a perfectly ordinary way for this to fail, and
+    // it must map onto the taxonomy rather than escaping as a SyntaxError.
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        payload = undefined;
+    }
+    if (response.status !== 200) {
+        throw mapFailure(response.status, payload, appSecret);
+    }
+    return readToken(payload);
+}
+// ─── Validation ────────────────────────────────────────────────────────
+/**
+ * Refuse to run in a browser.
+ *
+ * This package's entire threat model is that `appSecret` never leaves the
+ * server. Everything else here — the redaction, the non-enumerable `cause`, the
+ * never-a-garbage-token property — defends a secret that is already in the right
+ * place. None of it helps if the secret was bundled into a page, where every
+ * visitor can read it and mint an identity for any of your users. That is the
+ * one failure this package can detect itself, so it does, loudly, instead of
+ * documenting it and hoping.
+ *
+ * **Why BOTH `window` and `document`, and not either alone.** Edge runtimes
+ * (Cloudflare Workers, Vercel Edge, Deno Deploy) are legitimate places to mint
+ * from, and some of them define a `window`-ish global while defining no `document`
+ * — testing `window` alone would refuse a correct deployment. A DOM is the thing
+ * that actually distinguishes a page from a server-side JS runtime, so the pair
+ * is the discriminator and the conjunction is deliberate, not defensive noise.
+ *
+ * Called from every exported entry path. There is one today; anything added
+ * later calls this first, for the same reason.
+ *
+ * Probed through `globalThis` by name rather than written as
+ * `typeof window !== 'undefined'` because `lib` is pinned to `["ES2022"]` with
+ * no `dom`, so those identifiers do not exist for the compiler. Adding `dom`
+ * to satisfy the check would declare browser globals throughout a package whose
+ * whole point is that it does not run in one — the wrong fix. Comparing the
+ * value against `undefined` (rather than testing key presence) keeps the
+ * `typeof` semantics: a runtime that defines `globalThis.window = undefined` is
+ * not a browser and must not be refused.
+ */
+function globalIsDefined(name) {
+    return Reflect.get(globalThis, name) !== undefined;
+}
+function assertNotBrowser() {
+    if (globalIsDefined('window') && globalIsDefined('document')) {
+        throw new WidgetAuthConfigError('@guuey/widget-auth ran in a browser, and refused. Your app secret authorizes minting ' +
+            'an identity for ANY user of your app, so if this code reached a browser the secret is ' +
+            'in your shipped bundle and every visitor can read it — rotate it now with ' +
+            '`guuey widget keys rotate <appId> --new-secret`. Mint on your server instead and hand ' +
+            'the returned token to the widget: that is what the widget asks your backend for a ' +
+            'token rather than minting one itself.');
+    }
+}
+function requireNonEmpty(value, field) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new WidgetAuthConfigError(`${field} is required.`);
+    }
+}
+function requireWithin(value, max, field) {
+    if (value.length > max) {
+        throw new WidgetAuthConfigError(`${field} must be ${max} characters or less (got ${value.length}).`);
+    }
+}
+/**
+ * Resolve the API base, trimming trailing slashes so callers can pass either
+ * form without producing a `//v1/...` path.
+ */
+function resolveBaseUrl(configured) {
+    const raw = configured ?? readEnv('GUUEY_API_URL');
+    if (raw === undefined || raw.length === 0) {
+        throw new WidgetAuthConfigError('No guuey API base URL. Pass `apiBaseUrl` or set the GUUEY_API_URL environment variable ' +
+            '(for example https://api.guuey.com).');
+    }
+    return raw.replace(/\/+$/, '');
+}
+/**
+ * Read an environment variable without assuming a Node-shaped global.
+ *
+ * The tolerance is for EDGE RUNTIMES — Cloudflare Workers, Vercel Edge, Deno
+ * Deploy — which are legitimate places to mint from and may not expose
+ * `process`. It is emphatically not tolerance for browsers, which
+ * {@link assertNotBrowser} refuses outright; an earlier version of this comment
+ * said "edge or browser bundle", which read as sanctioning exactly the
+ * deployment this package exists to prevent.
+ */
+function readEnv(name) {
+    if (typeof process === 'undefined')
+        return undefined;
+    return process.env?.[name];
+}
+function buildBody(appId, user, ttlSeconds) {
+    requireNonEmpty(user.userId, 'userId');
+    requireWithin(user.userId, MAX_USER_ID_LENGTH, 'userId');
+    const body = { appId, userId: user.userId };
+    if (user.name !== undefined) {
+        requireWithin(user.name, MAX_NAME_LENGTH, 'name');
+        body.name = user.name;
+    }
+    if (user.email !== undefined) {
+        requireWithin(user.email, MAX_EMAIL_LENGTH, 'email');
+        body.email = user.email;
+    }
+    if (ttlSeconds !== undefined) {
+        if (!Number.isInteger(ttlSeconds) ||
+            ttlSeconds < MIN_TTL_SECONDS ||
+            ttlSeconds > MAX_TTL_SECONDS) {
+            throw new WidgetAuthConfigError(`ttlSeconds must be a whole number of seconds between ${MIN_TTL_SECONDS} and ${MAX_TTL_SECONDS} (got ${ttlSeconds}).`);
+        }
+        body.ttlSeconds = ttlSeconds;
+    }
+    return body;
+}
+function resolveFetch(configured) {
+    if (configured !== undefined)
+        return configured;
+    if (typeof globalThis.fetch !== 'function') {
+        throw new WidgetAuthConfigError('No global fetch available. @guuey/widget-auth needs Node 18 or newer, or a `fetch` ' +
+            'implementation passed as `config.fetch`.');
+    }
+    const globalFetch = globalThis.fetch;
+    return (url, init) => globalFetch(url, init);
+}
+// ─── Response handling ─────────────────────────────────────────────────
+/** Pull `error.message` out of the service's error envelope, if it has one. */
+function serviceMessage(payload, secret) {
+    if (typeof payload !== 'object' || payload === null)
+        return undefined;
+    const error = payload.error;
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    const message = error.message;
+    if (typeof message !== 'string' || message.length === 0)
+        return undefined;
+    return truncate(redactSecret(message, secret), MAX_SERVICE_MESSAGE_LENGTH);
+}
+/** Describe a thrown value for a message, redacted and bounded. */
+function describe(err, secret) {
+    const text = err instanceof Error ? err.message : String(err);
+    return truncate(redactSecret(text, secret), MAX_SERVICE_MESSAGE_LENGTH);
+}
+function truncate(text, max) {
+    return text.length <= max ? text : `${text.slice(0, max)}…`;
+}
+/** Map a non-200 onto the taxonomy. */
+function mapFailure(status, payload, secret) {
+    const detail = serviceMessage(payload, secret);
+    const suffix = detail === undefined ? '' : ` ${detail}`;
+    if (status === 401) {
+        return new WidgetAuthCredentialError('The widget app secret was not accepted. It may be wrong, revoked, or for a different app — ' +
+            'these are deliberately indistinguishable, so that this route cannot be used to discover ' +
+            `which apps exist. Check the secret, then \`guuey widget keys\`.${suffix}`, status);
+    }
+    if (status === 409) {
+        return new WidgetAuthAppNotConfiguredError(`The app is not configured to accept tokens from its own widget issuer.${suffix}`, status);
+    }
+    if (status === 400) {
+        return new WidgetAuthRequestError('The token service rejected the request. @guuey/widget-auth validates these fields itself, ' +
+            `so this usually means it is out of date with the deployed API.${suffix}`, status);
+    }
+    if (status >= 500) {
+        return new WidgetAuthServiceError(`The guuey token service failed (HTTP ${status}). This is usually transient — retry with backoff.${suffix}`, status, true);
+    }
+    return new WidgetAuthServiceError(`Unexpected response from the guuey token service (HTTP ${status}).${suffix}`, status, false);
+}
+/**
+ * Validate a 200 body into a {@link WidgetToken}.
+ *
+ * Every field is checked before anything is returned. A 200 carrying a body this
+ * package cannot recognize is an ERROR, never a best-effort object: the caller
+ * hands the result to a browser, so a `token` that is `undefined`, empty, or a
+ * number would become an authentication failure surfacing far from its cause —
+ * or, worse, a value from a response nobody authenticated.
+ */
+function readToken(payload) {
+    const unusable = (why) => new WidgetAuthServiceError(`The guuey token service returned a response this package cannot use: ${why}. ` +
+        'No token was issued.', 200, false);
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) {
+        throw unusable('the body was not a JSON object');
+    }
+    const body = payload;
+    if (typeof body.token !== 'string' || body.token.length === 0) {
+        throw unusable('`token` was missing or not a non-empty string');
+    }
+    if (typeof body.expiresAtEpoch !== 'number' || !Number.isFinite(body.expiresAtEpoch)) {
+        throw unusable('`expiresAtEpoch` was missing or not a number');
+    }
+    if (typeof body.issuer !== 'string' || typeof body.kid !== 'string') {
+        throw unusable('`issuer` or `kid` was missing');
+    }
+    return {
+        token: body.token,
+        expiresAtEpoch: body.expiresAtEpoch,
+        issuer: body.issuer,
+        kid: body.kid,
+    };
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@guuey/widget-auth",
+  "version": "0.1.0",
+  "description": "Mint end-user identity tokens for a guuey embeddable widget from your own backend. One call, zero runtime dependencies — your app secret stays on your server and the platform holds the signing key.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "rm -rf dist && pnpm build",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run && pnpm run smoke:dist",
+    "test:watch": "vitest",
+    "smoke:dist": "pnpm build && node scripts/import-smoke.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "24.12.4",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "guuey",
+    "widget",
+    "embed",
+    "auth",
+    "jwt",
+    "identity"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withguuey/guuey-sdks.git",
+    "directory": "packages/widget-auth"
+  },
+  "homepage": "https://guuey.com",
+  "bugs": {
+    "url": "https://github.com/loqu-co/guuey/issues"
+  }
+}