@9in-io/sdk 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## 0.3.0
+
+- `WebAppAuth` (`@9in-io/sdk/server`): sign-in for server-rendered apps (authorization code +
+  PKCE, with or without a client secret), using only `fetch` and Web Crypto, so it runs on Node,
+  Next.js Edge, Cloudflare Workers, Deno and Bun. `createLogin`, `handleCallback` (state, RFC 9207
+  issuer check and ID token verification), `refresh`, `logoutUrl`, `revoke`, `userInfo`. It's the
+  base of `@9in-io/nextjs`; you keep the transaction and session where you like.
+- `verifyIdToken`: signature, issuer, audience (`azp` with several), expiry and nonce.
+
+## 0.2.0
+
+Breaking: 9in's wire formats are now snake_case throughout, with ISO 8601 UTC times
+(see "API conventions" in the docs). Needs the 9in release of 2026-11-10.
+
+- `WebhookEvent`: `type` → `event_type`, `createdAt` → `created_at`; `data.userId` is gone, use
+  `data.user.id`. For `user.deleted`, `data.user` is the user as it was before the deletion.
+  `token.revoked` data has `token_type` and `client_id`.
+- `ManagedUser`: `created_at`, `updated_at`, `last_login_at` (ISO strings), `login_count`,
+  and every profile field.
+- `ManagedSession`: `user_id`, `auth_time`, `user_agent`, `created_at`, `last_seen_at`,
+  `expires_at` (ISO strings); `revokedAt` removed.
+- `getUser` returns `ManagedUserDetail` (`user`, `identities`, `sessions`, `has_password`,
+  `mfa`); `listUsers` returns `next_cursor`.
+- `NewUser` / `ImportUser`: `email_verified`, `phone_number`, `phone_number_verified`,
+  `password_hash`, and ISO `created_at` / `last_login_at`. The server refuses the old names.
+- `findUser("phone_number", …)` replaces `findUser("phone", …)`.
+- `createLoginLink` returns `expires_at` as an ISO string.
+- `AdapterEvent`: `event_type`, `created_at`, and `data.user_id` / `data.expires_at`.
+- `TokenVerifier.handleEvent` reads the new webhook shape.
+- The package ships `src/` too, so the `@9in/source` export condition resolves (0.1.x listed
+  it without shipping the files, which broke bundlers configured with that condition).

package/README.md

@@ -30,6 +30,34 @@ const res = await auth.fetch("https://api.acme.com/orders");
 await auth.logout({ returnTo: location.origin });
 ```
 
+## Sign users in (server-rendered apps)
+
+`WebAppAuth` runs the sign-in on your server: Node, Next.js (also Edge), Cloudflare Workers,
+Deno and Bun. You keep the transaction (between the redirect and the callback) and the session,
+for example in encrypted cookies. With Next.js, `@9in-io/nextjs` does all of that for you.
+
+```ts
+import { WebAppAuth } from "@9in-io/sdk/server";
+
+const auth = new WebAppAuth({
+  issuer: "https://acme.9in.io",
+  clientId: process.env.NINE_CLIENT_ID!,
+  clientSecret: process.env.NINE_CLIENT_SECRET, // confidential apps; leave out for public ones
+  redirectUri: "https://app.acme.com/auth/callback",
+});
+
+// /auth/login
+const { url, transaction } = await auth.createLogin({ returnTo: "/dashboard" });
+// store `transaction` (encrypted, ~15 minutes), then redirect to `url`
+
+// /auth/callback
+const { tokens, claims, returnTo } = await auth.handleCallback(request.url, transaction);
+// claims: the verified ID token (sub, email, name, amr…); tokens: access, refresh, ID token
+
+const fresh = await auth.refresh(tokens.refreshToken!);  // 9in rotates refresh tokens: keep the new one
+const bye = await auth.logoutUrl({ idTokenHint: tokens.idToken, postLogoutRedirectUri: "https://app.acme.com/" });
+```
+
 ## Protect your API (server)
 
 ```ts
@@ -88,9 +116,10 @@ webhook events, or a short `cacheTtl`.
 import { ManagementClient } from "@9in-io/sdk/server";
 
 const nine = new ManagementClient({ issuer, clientId, clientSecret }); // app with management scopes
-await nine.createUser({ email: "jane@acme.com", password: "…", emailVerified: true });
+await nine.createUser({ email: "jane@acme.com", password: "…", email_verified: true });
+await nine.updateUser(userId, { phone_number: "+447700900000", phone_number_verified: true });
 await nine.blockUser(userId);
-const { user } = await nine.findUser("phone", "+447700900000"); // or "email", "username"
+const { user } = await nine.findUser("phone_number", "+447700900000"); // or "email", "username"
 
 // Sessions: list them, end one (its sid), or sign the user out everywhere
 const { sessions } = await nine.listUserSessions(userId);
@@ -101,9 +130,16 @@ await nine.revokeUserSessions(userId);
 const { url } = await nine.createLoginLink(userId, { returnTo: "https://app.acme.com/callback", ttlSeconds: 600 });
 
 // Bulk import (500 per call): old ids, password hashes (bcrypt, argon2, PBKDF2, Firebase scrypt), social identities
-const { results } = await nine.importUsers([{ id: "auth0|42", email: "jane@acme.com", passwordHash: "$2b$10$…" }], { onConflict: "skip", source: "auth0" });
+const { results } = await nine.importUsers(
+  [{ id: "auth0|42", email: "jane@acme.com", password_hash: "$2b$10$…", created_at: "2021-03-04T05:06:07Z" }],
+  { onConflict: "skip", source: "auth0" },
+);
 ```
 
+Users, sessions and requests use snake_case field names, the same going in and coming out
+(`email_verified`, `phone_number`, `password_hash`), and times are ISO 8601 UTC strings
+(`created_at`, `last_login_at`). Method options stay camelCase (`returnTo`, `onConflict`).
+
 ## Keep users in your own database (adapter)
 
 ```ts
@@ -123,7 +159,8 @@ export default {
       return user ? toAdapterUser(user) : null;
     },
     async onEvent(event) {
-      if (event.type === "otp.requested") await sendCode(event.data);
+      // { id, event_type, created_at, data }; data.user_id is your own user id
+      if (event.event_type === "otp.requested") await sendCode(event.data); // user_id, channel, to, code, purpose, expires_at
     },
   }),
 };
@@ -144,8 +181,9 @@ import { verifyWebhook } from "@9in-io/sdk/server";
 export default {
   async fetch(request: Request, env: { NINE_WEBHOOK_SECRET: string }) {
     const event = await verifyWebhook(env.NINE_WEBHOOK_SECRET, request);
-    // event.id is the same on every retry and redelivery: ignore ones you have seen.
-    if (event.type === "user.created") await addToCrm(event.data.user);
+    // { id, event_type, created_at, tenant, environment, data }. event.id is the same on every
+    // retry and redelivery: ignore ones you have seen. data.user is the user the event is about.
+    if (event.event_type === "user.created") await addToCrm(event.data.user);
     return new Response(null, { status: 204 });
   },
 };

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 export { NineError, normalizeIssuer } from "./util.js";
+export { WebAppAuth, type WebAppAuthOptions, type WebLoginOptions, type LoginTransaction, type WebTokenSet, type CallbackResult } from "./web-app.js";
 export interface VerifyOptions {
     /** Your tenant's issuer (exactly as in the token's iss claim). */
     issuer: string;
@@ -39,6 +40,43 @@ export interface AccessTokenClaims {
  * `createTokenVerifier` (hybrid mode) when revocation must take effect at once.
  */
 export declare function verifyAccessToken(token: string | null | undefined, options: VerifyOptions): Promise<AccessTokenClaims>;
+export interface VerifyIdTokenOptions {
+    /** Your tenant's issuer URL. */
+    issuer: string;
+    /** Your application's client ID (the token's audience). */
+    clientId: string;
+    /** The nonce sent with the sign-in request. */
+    nonce?: string | null;
+    /** For tenants whose signing key is a shared (HMAC) secret. */
+    secret?: string;
+    /** Seconds of clock skew allowed (default 30). */
+    clockTolerance?: number;
+    fetch?: typeof fetch;
+    allowInsecureIssuer?: boolean;
+}
+/** Claims of a verified ID token (standard OIDC claims plus your custom profile claims). */
+export interface IdTokenClaims {
+    iss: string;
+    sub: string;
+    aud: string | string[];
+    exp: number;
+    iat: number;
+    nonce?: string;
+    auth_time?: number;
+    /** How the user signed in, e.g. ["pwd", "mfa", "otp"]. */
+    amr?: string[];
+    sid?: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    picture?: string;
+    [claim: string]: unknown;
+}
+/**
+ * Verifies an ID token from your tenant: signature (JWKS, or the shared secret for HMAC keys),
+ * issuer, audience (your client ID; `azp` when there are several), expiry and nonce.
+ */
+export declare function verifyIdToken(token: string | null | undefined, options: VerifyIdTokenOptions): Promise<IdTokenClaims>;
 export type VerificationMode = "local" | "hybrid" | "introspect";
 export interface TokenVerifierOptions extends Omit<VerifyOptions, "scope"> {
     /**
@@ -69,7 +107,7 @@ export interface TokenVerifier {
      * user.sessions_revoked, user.updated and user.deleted).
      */
     handleEvent(event: {
-        type: string;
+        event_type: string;
         data: Record<string, unknown>;
     }): number;
     /** Forgets every cached answer. */
@@ -94,42 +132,73 @@ export interface ManagementOptions {
     allowInsecureIssuer?: boolean;
     fetch?: typeof fetch;
 }
+/** A user as the Management API and webhooks send it. Times are ISO 8601 UTC strings. */
 export interface ManagedUser {
     id: string;
     email: string | null;
     email_verified: boolean;
     phone_number: string | null;
+    phone_number_verified: boolean;
     username: string | null;
+    preferred_username: string | null;
     name: string | null;
+    given_name: string | null;
+    middle_name: string | null;
+    family_name: string | null;
+    nickname: string | null;
+    gender: string | null;
+    website: string | null;
     picture: string | null;
+    locale: string | null;
+    zoneinfo: string | null;
+    birthdate: string | null;
     blocked: boolean;
     metadata: Record<string, unknown>;
-    createdAt: number;
-    lastLoginAt: number | null;
-    [field: string]: unknown;
+    created_at: string;
+    updated_at: string;
+    last_login_at: string | null;
+    login_count: number;
 }
-/** An active sign-in session (`sid` is the `sid` claim of its tokens). Times are ms since epoch. */
+/** An active sign-in session (`sid` is the `sid` claim of its tokens). Times are ISO 8601 UTC strings. */
 export interface ManagedSession {
     sid: string;
-    userId: string;
-    authTime: number;
+    user_id: string;
+    auth_time: string;
     amr: string[];
     ip: string;
-    userAgent: string;
-    createdAt: number;
-    lastSeenAt: number;
-    expiresAt: number;
-    revokedAt: number | null;
+    user_agent: string;
+    created_at: string;
+    last_seen_at: string;
+    expires_at: string;
+}
+/** A linked sign-in of a user (`social:google`, `enterprise:<id>`, `adapter`, …). */
+export interface ManagedIdentity {
+    connection: string;
+    subject: string;
+    profile: Record<string, unknown>;
+    created_at: string;
+}
+/** `getUser`: the user with their identities, active sessions and two-factor state. */
+export interface ManagedUserDetail {
+    user: ManagedUser;
+    identities: ManagedIdentity[];
+    sessions: ManagedSession[];
+    has_password: boolean;
+    mfa: {
+        enabled: boolean;
+        enabled_at?: string;
+        recovery_codes_left?: number;
+    };
 }
 /** One record for `importUsers`: the fields of `createUser` plus what an import may carry over. */
 export interface ImportUser {
     /** Keep the id from your old system (letters, digits and | _ . : @ + -, max 128). */
     id?: string;
     email?: string | null;
-    emailVerified?: boolean;
+    email_verified?: boolean;
     /** E.164, e.g. +447700900000. */
-    phone?: string | null;
-    phoneVerified?: boolean;
+    phone_number?: string | null;
+    phone_number_verified?: boolean;
     username?: string | null;
     name?: string | null;
     given_name?: string | null;
@@ -140,21 +209,21 @@ export interface ImportUser {
     birthdate?: string | null;
     metadata?: Record<string, unknown>;
     blocked?: boolean;
-    /** A plain password (at most 50 such records per call), or `passwordHash` from your old system. */
+    /** A plain password (at most 50 such records per call), or `password_hash` from your old system. */
     password?: string;
     /** bcrypt, argon2, PBKDF2 or Firebase scrypt hash: users keep their password. */
-    passwordHash?: string;
+    password_hash?: string;
     /** Linked sign-ins, e.g. { connection: "social:google", subject: "1069…" }. */
     identities?: {
         connection: string;
         subject: string;
     }[];
-    /** ms since epoch */
-    createdAt?: number;
-    lastLoginAt?: number;
+    /** Original dates, ISO 8601 (`Z` or an offset). */
+    created_at?: string;
+    last_login_at?: string;
 }
-/** Fields of a new user (`createUser`, `updateUser`). */
-export type NewUser = Omit<ImportUser, "id" | "identities" | "createdAt" | "lastLoginAt">;
+/** Fields of a new user (`createUser`); `updateUser` takes any of them. */
+export type NewUser = Omit<ImportUser, "id" | "identities" | "created_at" | "last_login_at">;
 export type ImportResult = {
     index: number;
     ok: boolean;
@@ -185,16 +254,16 @@ export declare class ManagementClient {
         limit?: number;
     }): Promise<{
         users: ManagedUser[];
-        nextCursor: string | null;
-    }>;
-    getUser(id: string): Promise<{
-        user: ManagedUser;
+        next_cursor: string | null;
+        total: number;
     }>;
+    /** The user with their identities, active sessions and two-factor state. */
+    getUser(id: string): Promise<ManagedUserDetail>;
     findUserByEmail(email: string): Promise<{
         user: ManagedUser;
     }>;
-    /** Looks a user up by email, phone (E.164) or username; throws `not_found` (404) when unknown. */
-    findUser(type: "email" | "phone" | "username", value: string): Promise<{
+    /** Looks a user up by email, phone number (E.164) or username; throws `not_found` (404) when unknown. */
+    findUser(type: "email" | "phone_number" | "username", value: string): Promise<{
         user: ManagedUser;
     }>;
     createUser(input: NewUser): Promise<{
@@ -211,7 +280,8 @@ export declare class ManagementClient {
     }): Promise<{
         results: ImportResult[];
     }>;
-    updateUser(id: string, input: Record<string, unknown>): Promise<{
+    /** Changes only the fields you send; `metadata` is replaced as a whole. */
+    updateUser(id: string, input: Partial<NewUser>): Promise<{
         user: ManagedUser;
     }>;
     deleteUser(id: string): Promise<void>;
@@ -228,7 +298,7 @@ export declare class ManagementClient {
         ttlSeconds?: number;
     }): Promise<{
         url: string;
-        expires_at: number;
+        expires_at: string;
     }>;
     /** The user's active sessions, most recently used first. */
     listUserSessions(id: string): Promise<{
@@ -262,11 +332,20 @@ export interface AdapterUser {
     blocked?: boolean | null;
     metadata?: Record<string, unknown> | null;
 }
+/**
+ * What 9in POSTs to `…/event`. `data.user_id` is your own user id. `otp.requested` carries
+ * `user_id, channel, to, code, purpose, expires_at`; `user.updated` and
+ * `user.password_changed` carry `user_id, fields`.
+ */
 export interface AdapterEvent {
     id: string;
-    type: "otp.requested" | "user.created" | "user.updated" | "user.password_changed" | "session.revoked";
-    createdAt: string;
-    data: Record<string, unknown>;
+    event_type: "otp.requested" | "user.created" | "user.updated" | "user.password_changed" | "session.revoked";
+    /** ISO 8601 UTC. */
+    created_at: string;
+    data: {
+        user_id?: string;
+        [field: string]: unknown;
+    };
 }
 export interface AdapterHandlers {
     /** Shared secret from the console (Connections → User database). Several allow rotation. */
@@ -291,14 +370,18 @@ export type WebhookEventType = "user.created" | "user.updated" | "user.deleted"
 export interface WebhookEvent<Data extends Record<string, unknown> = Record<string, unknown>> {
     /** Event id: the same on every retry and redelivery, so you can ignore duplicates. */
     id: string;
-    type: WebhookEventType;
-    createdAt: string;
+    /** The event name, also in the `9in-event-type` header. */
+    event_type: WebhookEventType;
+    /** ISO 8601 UTC. */
+    created_at: string;
     /** Tenant id (tnt_…). */
     tenant: string;
     environment: "production" | "sandbox";
-    /** Event details, plus `userId` and a `user` snapshot (null once deleted) for user events. */
+    /**
+     * Event details, plus the `user` the event is about (null when there is none; for
+     * `user.deleted`, the user as it was just before the deletion).
+     */
     data: Data & {
-        userId?: string | null;
         user?: ManagedUser | null;
     };
 }
@@ -314,7 +397,7 @@ export interface VerifyWebhookOptions {
  * the body, so pass `request.clone()` if you need it afterwards.
  *
  *   const event = await verifyWebhook(env.NINE_WEBHOOK_SECRET, request);
- *   if (event.type === "user.created") …
+ *   if (event.event_type === "user.created") …
  */
 export declare function verifyWebhook(secret: string | string[], request: Request, options?: VerifyWebhookOptions): Promise<WebhookEvent>;
 /**

package/dist/server.js

@@ -1,5 +1,6 @@
 import { NineError, decodeJwt, discover, normalizeIssuer, postForm, toHex, utf8 } from "./util.js";
 export { NineError, normalizeIssuer } from "./util.js";
+export { WebAppAuth } from "./web-app.js";
 /** WebCrypto parameters for each JWS algorithm 9in signs with. */
 const ALGORITHMS = {
     RS256: { import: { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, verify: "RSASSA-PKCS1-v1_5" },
@@ -111,6 +112,57 @@ export async function verifyAccessToken(token, options) {
     checkClaims(payload, issuer, options);
     return payload;
 }
+/**
+ * Verifies an ID token from your tenant: signature (JWKS, or the shared secret for HMAC keys),
+ * issuer, audience (your client ID; `azp` when there are several), expiry and nonce.
+ */
+export async function verifyIdToken(token, options) {
+    if (!token)
+        throw new NineError("invalid_token", "missing ID token", 401);
+    const fetcher = options.fetch ?? fetch.bind(globalThis);
+    const issuer = normalizeIssuer(options.issuer, options.allowInsecureIssuer);
+    let parts;
+    try {
+        parts = decodeJwt(token);
+    }
+    catch {
+        throw new NineError("invalid_token", "malformed ID token", 401);
+    }
+    const { header, payload, signingInput, signature } = parts;
+    const alg = String(header.alg);
+    // An access token is never accepted as an ID token.
+    if (ACCESS_TOKEN_TYPES.has(String(header.typ ?? "").toLowerCase()))
+        throw new NineError("invalid_token", "not an ID token", 401);
+    let valid;
+    if (HMAC_HASH[alg]) {
+        if (!options.secret)
+            throw new NineError("invalid_token", "HMAC-signed ID token: pass the tenant's shared secret", 401);
+        const key = await crypto.subtle.importKey("raw", utf8(options.secret), { name: "HMAC", hash: HMAC_HASH[alg] }, false, ["verify"]);
+        valid = await crypto.subtle.verify("HMAC", key, signature, utf8(signingInput));
+    }
+    else if (ALGORITHMS[alg]) {
+        const jwk = await findKey(issuer, header.kid, fetcher);
+        if (!jwk)
+            throw new NineError("invalid_token", "unknown signing key", 401);
+        if (jwk.alg && jwk.alg !== alg)
+            throw new NineError("invalid_token", "algorithm does not match the key", 401);
+        valid = await crypto.subtle.verify(ALGORITHMS[alg].verify, await importPublicKey(jwk, alg), signature, utf8(signingInput));
+    }
+    else {
+        throw new NineError("invalid_token", "unsupported algorithm", 401);
+    }
+    if (!valid)
+        throw new NineError("invalid_token", "bad signature", 401);
+    checkClaims(payload, issuer, { issuer, audience: options.clientId, clockTolerance: options.clockTolerance });
+    const aud = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+    if (aud.length > 1 && payload.azp !== options.clientId)
+        throw new NineError("invalid_token", "authorized party mismatch", 401);
+    if (options.nonce !== undefined && options.nonce !== null && payload.nonce !== options.nonce)
+        throw new NineError("invalid_token", "nonce mismatch", 401);
+    if (typeof payload.sub !== "string" || !payload.sub)
+        throw new NineError("invalid_token", "missing subject", 401);
+    return payload;
+}
 function checkClaims(payload, issuer, options) {
     const now = Math.floor(Date.now() / 1000);
     const skew = options.clockTolerance ?? 30;
@@ -221,13 +273,14 @@ export function createTokenVerifier(options) {
         },
         handleEvent(event) {
             const data = event.data ?? {};
+            const userId = data.user?.id;
             let match = null;
-            if (event.type === "token.revoked" && data.type === "access_token" && data.jti)
+            if (event.event_type === "token.revoked" && data.token_type === "access_token" && data.jti)
                 match = (c) => c.jti === data.jti;
-            else if (event.type === "session.revoked" && data.sid)
+            else if (event.event_type === "session.revoked" && data.sid)
                 match = (c) => c.sid === data.sid;
-            else if (["user.sessions_revoked", "user.deleted", "user.updated", "user.password_changed"].includes(event.type) && data.userId) {
-                match = (c) => c.sub === data.userId;
+            else if (["user.sessions_revoked", "user.deleted", "user.updated", "user.password_changed"].includes(event.event_type) && typeof userId === "string") {
+                match = (c) => c.sub === userId;
             }
             if (!match)
                 return 0;
@@ -289,13 +342,14 @@ export class ManagementClient {
             params.set("limit", String(options.limit));
         return this.request("GET", `/users?${params}`);
     }
+    /** The user with their identities, active sessions and two-factor state. */
     getUser(id) {
         return this.request("GET", `/users/${encodeURIComponent(id)}`);
     }
     findUserByEmail(email) {
         return this.findUser("email", email);
     }
-    /** Looks a user up by email, phone (E.164) or username; throws `not_found` (404) when unknown. */
+    /** Looks a user up by email, phone number (E.164) or username; throws `not_found` (404) when unknown. */
     findUser(type, value) {
         return this.request("GET", `/users/lookup?${type}=${encodeURIComponent(value)}`);
     }
@@ -314,6 +368,7 @@ export class ManagementClient {
             ...(options.source ? { source: options.source } : {}),
         });
     }
+    /** Changes only the fields you send; `metadata` is replaced as a whole. */
     updateUser(id, input) {
         return this.request("PATCH", `/users/${encodeURIComponent(id)}`, input);
     }
@@ -386,7 +441,7 @@ export async function signPayload(secret, method, path, body) {
  * the body, so pass `request.clone()` if you need it afterwards.
  *
  *   const event = await verifyWebhook(env.NINE_WEBHOOK_SECRET, request);
- *   if (event.type === "user.created") …
+ *   if (event.event_type === "user.created") …
  */
 export async function verifyWebhook(secret, request, options = {}) {
     const body = await request.text();

package/dist/web-app.d.ts

@@ -0,0 +1,96 @@
+import { type IdTokenClaims } from "./server.js";
+/**
+ * Sign-in for server-rendered web apps (authorization code + PKCE, with or without a client
+ * secret), using only `fetch` and Web Crypto: it runs on Node 18+, Next.js (Node and Edge),
+ * Cloudflare Workers, Deno and Bun. Framework packages keep the transaction and the session
+ * (for example in encrypted cookies); this class does the protocol:
+ *
+ *   const { url, transaction } = await auth.createLogin({ returnTo: "/dashboard" });
+ *   // keep `transaction` until the callback, redirect the browser to `url`
+ *   const { tokens, claims, returnTo } = await auth.handleCallback(request.url, transaction);
+ */
+export interface WebAppAuthOptions {
+    /** Your tenant's issuer URL, e.g. https://acme.9in.io. */
+    issuer: string;
+    clientId: string;
+    /** For confidential applications: sent with HTTP Basic. Leave out for public ones (PKCE only). */
+    clientSecret?: string;
+    /** Your callback URL, as registered on the application. */
+    redirectUri: string;
+    /** Default "openid profile email offline_access" (offline_access gives a refresh token). */
+    scope?: string;
+    /** An API identifier, to get access tokens for that API. */
+    audience?: string;
+    /** Only for tenants that sign with a shared (HMAC) key. */
+    idTokenSecret?: string;
+    fetch?: typeof fetch;
+    /** Allows http:// issuers other than localhost (never in production). */
+    allowInsecureIssuer?: boolean;
+}
+export interface WebLoginOptions {
+    /** A path in your app to come back to after sign-in. */
+    returnTo?: string;
+    prompt?: "login" | "consent" | "none" | "select_account" | "create";
+    /** Prefills the identifier on the sign-in page. */
+    loginHint?: string;
+    /** "signup" opens the registration page. */
+    screen?: "login" | "signup";
+    /** Language of the hosted pages (ui_locales), e.g. "de". */
+    locale?: string;
+    /** Extra authorization parameters (they never replace state, nonce or PKCE). */
+    params?: Record<string, string>;
+}
+/** What to keep between the redirect to 9in and the callback (store it encrypted; it's secret). */
+export interface LoginTransaction {
+    state: string;
+    nonce: string;
+    verifier: string;
+    returnTo?: string;
+    /** ms */
+    createdAt: number;
+}
+export interface WebTokenSet {
+    accessToken: string;
+    idToken: string | null;
+    refreshToken: string | null;
+    /** ms */
+    expiresAt: number;
+    scope: string;
+    tokenType: string;
+}
+export interface CallbackResult {
+    tokens: WebTokenSet;
+    /** The verified ID token's claims: the signed-in user. */
+    claims: IdTokenClaims;
+    returnTo?: string;
+}
+export declare class WebAppAuth {
+    private readonly options;
+    private readonly issuer;
+    private readonly fetcher;
+    constructor(options: WebAppAuthOptions);
+    /** The URL to send the browser to, and the transaction to keep until the callback. */
+    createLogin(options?: WebLoginOptions): Promise<{
+        url: string;
+        transaction: LoginTransaction;
+    }>;
+    /**
+     * Finishes sign-in on your callback URL: checks the state against the transaction, exchanges
+     * the code and verifies the ID token (signature, issuer, audience, expiry, nonce).
+     */
+    handleCallback(callbackUrl: string | URL, transaction: LoginTransaction | null | undefined): Promise<CallbackResult>;
+    /** New tokens from a refresh token (9in rotates it: keep the one returned). */
+    refresh(refreshToken: string): Promise<WebTokenSet>;
+    /** The URL that ends the session at 9in and comes back to `postLogoutRedirectUri`. */
+    logoutUrl(options?: {
+        idTokenHint?: string | null;
+        postLogoutRedirectUri?: string;
+        state?: string;
+    }): Promise<string>;
+    /** Revokes a refresh token (ending the session's token family) or an access token. */
+    revoke(token: string, hint?: "refresh_token" | "access_token"): Promise<void>;
+    /** The user's current profile from the userinfo endpoint. */
+    userInfo(accessToken: string): Promise<Record<string, unknown>>;
+    private clientAuth;
+    private tokenRequest;
+}