@9in-io/sdk 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,186 @@
-# Temporary Holding Version
+# @9in-io/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official SDK for [9in](https://9in.io). Zero dependencies; runs in browsers, Node 18+,
+Cloudflare Workers, Deno and Bun.
+
+```bash
+npm install @9in-io/sdk
+```
+
+## Sign users in (browser)
+
+```ts
+import { NineAuth } from "@9in-io/sdk";
+
+const auth = new NineAuth({
+  issuer: "https://acme.9in.io",        // or your custom domain
+  clientId: "app_7f3k2m9q",
+  redirectUri: `${location.origin}/callback`,
+  audience: "https://api.acme.com",     // optional: access tokens for your API
+});
+
+await auth.login();                      // authorization code + PKCE
+await auth.signup();                     // opens the sign-up form (prompt=create)
+
+// on /callback
+const { user, returnTo } = await auth.handleRedirect();
+
+const token = await auth.getAccessToken();   // refreshed (and rotated) automatically
+const res = await auth.fetch("https://api.acme.com/orders");
+await auth.logout({ returnTo: location.origin });
+```
+
+## Protect your API (server)
+
+```ts
+import { verifyAccessToken } from "@9in-io/sdk/server";
+
+const claims = await verifyAccessToken(bearer, {
+  issuer: "https://acme.9in.io",
+  audience: "https://api.acme.com",
+  scope: "orders:read",
+});
+```
+
+Tokens are verified locally against your tenant's JWKS (cached; refetched once when a
+new key appears after rotation). Every algorithm of the 9in key library is supported:
+RS256/384/512, PS256/384/512, ES256, ES384 and EdDSA through JWKS, and HS256/384/512 when
+your API uses a shared secret (`secret: process.env.NINE_API_SECRET`). The key's own
+algorithm is enforced, and only access tokens (`typ: at+jwt`) are accepted.
+
+### Revocation: hybrid verification
+
+A local check cannot see revocations: a token revoked through `/oauth/revoke`, a sign-out
+or a blocked user keeps passing until it expires. `createTokenVerifier` closes that gap:
+
+```ts
+import { createTokenVerifier, verifyWebhook } from "@9in-io/sdk/server";
+
+const verifier = createTokenVerifier({
+  issuer: "https://acme.9in.io",
+  audience: "https://api.acme.com",
+  clientId: process.env.NINE_CLIENT_ID,       // a confidential application
+  clientSecret: process.env.NINE_CLIENT_SECRET,
+  mode: "hybrid",                              // default
+  cacheTtl: 300,                               // seconds an answer is trusted without news
+});
+
+const claims = await verifier.verify(bearer, { scope: "orders:read" });
+
+// Webhook endpoint subscribed to token.revoked, session.revoked and user.* events
+const event = await verifyWebhook(process.env.NINE_WEBHOOK_SECRET, request);
+verifier.handleEvent(event);
+```
+
+| Mode | What it does |
+|---|---|
+| `local` | Signature and claims only. No calls to 9in. |
+| `hybrid` | Local check, then one introspection per token. The answer is cached until a webhook says otherwise or `cacheTtl` passes; a refusal is cached until the token expires. |
+| `introspect` | Introspection on every call. |
+
+Opaque access tokens (`9in_at_…`, enabled per tenant or per API) are always introspected,
+and cached in hybrid mode. The cache is in memory, per process. Each process needs the
+webhook events, or a short `cacheTtl`.
+
+## Manage users (server)
+
+```ts
+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.blockUser(userId);
+const { user } = await nine.findUser("phone", "+447700900000"); // or "email", "username"
+
+// Sessions: list them, end one (its sid), or sign the user out everywhere
+const { sessions } = await nine.listUserSessions(userId);
+await nine.revokeSession(sessions[0].sid);
+await nine.revokeUserSessions(userId);
+
+// Single-use sign-in link (magic links, moving a signed-in user from your app to 9in)
+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" });
+```
+
+## Keep users in your own database (adapter)
+
+```ts
+import { adapterHandler } from "@9in-io/sdk/server";
+
+export default {
+  fetch: adapterHandler({
+    secret: env.NINE_ADAPTER_SECRET,
+    async authenticate({ type, value }, password) {
+      const user = await db.findByLogin(type, value);
+      if (!user) return "invalid";
+      if (user.disabled) return "blocked";
+      return (await verify(password, user.hash)) ? toAdapterUser(user) : "invalid";
+    },
+    async findUser(query) {
+      const user = "id" in query ? await db.findById(query.id) : await db.findByLogin(query.identifier.type, query.identifier.value);
+      return user ? toAdapterUser(user) : null;
+    },
+    async onEvent(event) {
+      if (event.type === "otp.requested") await sendCode(event.data);
+    },
+  }),
+};
+```
+
+Requests and responses are signed with HMAC-SHA256 (`9in-signature`), and each response
+is bound to its request id.
+
+## Receive webhooks (server)
+
+Add an endpoint under **Advanced → Webhooks** in the console and keep the signing secret it
+shows once. `verifyWebhook` checks the `9in-signature` header against the raw body (and a
+5-minute timestamp tolerance) and returns the event, or throws `NineError` (`invalid_signature`).
+
+```ts
+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);
+    return new Response(null, { status: 204 });
+  },
+};
+```
+
+It reads the body, so pass `request.clone()` if you need it again. Behind a proxy that
+rewrites the URL, pass the path 9in posted to: `verifyWebhook(secret, request, { path: "/hooks/9in" })`.
+Several secrets (`[newSecret, oldSecret]`) are accepted while you rotate.
+
+### Process each event once
+
+9in retries a delivery until it gets a 2xx (for about a day), and a retry can arrive while a
+slow first attempt is still running. `processEventOnce` runs your handler once per event id:
+
+```ts
+import { processEventOnce, verifyWebhook, type EventStore } from "@9in-io/sdk/server";
+
+const event = await verifyWebhook(env.NINE_WEBHOOK_SECRET, request);
+const outcome = await processEventOnce(store, event.id, () => handle(event));
+// processed / duplicate → 204; in_progress → 409 (9in retries later); handler threw → id released, error rethrown (5xx)
+return new Response(null, { status: outcome.status === "in_progress" ? 409 : 204 });
+```
+
+`store` is an `EventStore` whose `add` is atomic (a Durable Object, D1/SQL with a unique key,
+Redis `SET NX EX`; not Workers KV). `MemoryEventStore` covers a single process. Processed ids
+are kept for 3 days by default (`ttlSeconds`).
+
+## Issuers must use https
+
+`NineAuth`, `verifyAccessToken` and `ManagementClient` reject an issuer that is not `https://`
+(`insecure_issuer`), so a typo cannot send tokens or credentials in clear text. Plain http is
+accepted for `localhost`, `*.localhost` and loopback addresses; for other development hosts
+(e.g. `http://auth:8897` in Docker) pass `allowInsecureIssuer: true`.
+
+## Errors
+
+Every failure is a `NineError` with a `code` (`login_required`, `invalid_token`,
+`insufficient_scope`, `invalid_grant`, `insecure_issuer`, …) and, for HTTP errors, a `status`.

package/dist/index.d.ts

@@ -0,0 +1,119 @@
+export { NineError, normalizeIssuer } from "./util.js";
+/**
+ * Browser sign-in for single-page apps (also works in React Native / Electron with a
+ * custom `storage` and `navigate`). Authorization code flow with PKCE, automatic
+ * refresh-token rotation, RP-initiated logout.
+ *
+ *   const auth = new NineAuth({ issuer, clientId, redirectUri });
+ *   await auth.login();               // redirect to the hosted login
+ *   await auth.handleRedirect();      // on the callback page
+ *   const user = await auth.getUser();
+ *   const token = await auth.getAccessToken();
+ */
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export interface NineAuthOptions {
+    /** Your tenant's issuer, e.g. https://acme.9in.io or https://login.acme.com */
+    issuer: string;
+    clientId: string;
+    redirectUri: string;
+    /** Default: "openid profile email offline_access". */
+    scope?: string;
+    /** API identifier to request access tokens for (aud claim). */
+    audience?: string;
+    /** Where tokens are kept. Default: localStorage (falls back to memory). */
+    storage?: StorageLike;
+    /** Where the PKCE verifier and state are kept during the redirect. Default: sessionStorage. */
+    transientStorage?: StorageLike;
+    /** Navigation hook (default: window.location.assign). */
+    navigate?: (url: string) => void;
+    /** Custom fetch (tests, React Native). */
+    fetch?: typeof fetch;
+    /** Language of the hosted pages (ui_locales). */
+    locale?: string;
+    /** Accept a plain-http issuer other than localhost (development only). */
+    allowInsecureIssuer?: boolean;
+}
+export interface LoginOptions {
+    /** "login" forces re-authentication, "consent" re-asks for consent, "none" fails instead of showing UI. */
+    prompt?: "login" | "consent" | "none" | "select_account";
+    /** Pre-fill the identifier field. */
+    loginHint?: string;
+    /** Open the sign-up form directly (prompt=create). */
+    screen?: "login" | "signup";
+    /** Where to send the user after handleRedirect (returned to you). */
+    returnTo?: string;
+    /** Extra authorization parameters. */
+    params?: Record<string, string>;
+}
+export interface TokenSet {
+    accessToken: string;
+    idToken: string | null;
+    refreshToken: string | null;
+    /** ms since epoch */
+    expiresAt: number;
+    scope: string;
+}
+export interface User {
+    sub: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    picture?: string;
+    phone_number?: string;
+    locale?: string;
+    [claim: string]: unknown;
+}
+export declare class NineAuth {
+    private readonly options;
+    private readonly issuer;
+    private readonly storage;
+    private readonly transient;
+    private readonly fetcher;
+    private readonly key;
+    private refreshing;
+    constructor(options: NineAuthOptions);
+    private navigate;
+    /** Builds the authorization URL and stores the PKCE verifier; `login()` navigates to it. */
+    buildLoginUrl(options?: LoginOptions): Promise<string>;
+    /** Redirects to the hosted login page. */
+    login(options?: LoginOptions): Promise<void>;
+    /** Opens the sign-up form directly. */
+    signup(options?: Omit<LoginOptions, "screen">): Promise<void>;
+    /**
+     * Completes sign-in on the callback page: checks state, exchanges the code with the PKCE
+     * verifier and stores the tokens. Removes the code from the address bar.
+     */
+    handleRedirect(url?: string): Promise<{
+        user: User;
+        returnTo?: string;
+    }>;
+    private sameIssuer;
+    private store;
+    /** Stored tokens (possibly expired). */
+    getTokens(): TokenSet | null;
+    /** True when there is a usable access token or a refresh token. */
+    isAuthenticated(): boolean;
+    /** Claims of the signed-in user from the ID token, or null. */
+    getUser(): Promise<User | null>;
+    /** Fresh claims from the userinfo endpoint. */
+    fetchUserInfo(): Promise<User>;
+    /**
+     * A valid access token, refreshed (with rotation) when it expires within a minute.
+     * Concurrent callers share one refresh. Throws `login_required` when signed out.
+     */
+    getAccessToken(): Promise<string>;
+    private refresh;
+    /** fetch() with the access token attached. */
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /** Clears local tokens, revokes the refresh token and ends the 9in session. */
+    logout(options?: {
+        returnTo?: string;
+        local?: boolean;
+    }): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,238 @@
+import { NineError, base64UrlEncode, decodeJwt, discover, normalizeIssuer, postForm, randomString, sha256 } from "./util.js";
+export { NineError, normalizeIssuer } from "./util.js";
+class MemoryStorage {
+    map = new Map();
+    getItem(key) {
+        return this.map.get(key) ?? null;
+    }
+    setItem(key, value) {
+        this.map.set(key, value);
+    }
+    removeItem(key) {
+        this.map.delete(key);
+    }
+}
+function defaultStorage(kind) {
+    try {
+        const store = globalThis[kind];
+        if (store) {
+            store.setItem("__9in", "1");
+            store.removeItem("__9in");
+            return store;
+        }
+    }
+    catch {
+        // storage disabled (private mode, sandboxed iframe)
+    }
+    return new MemoryStorage();
+}
+export class NineAuth {
+    options;
+    issuer;
+    storage;
+    transient;
+    fetcher;
+    key;
+    refreshing = null;
+    constructor(options) {
+        this.options = options;
+        if (!options.issuer || !options.clientId || !options.redirectUri)
+            throw new NineError("invalid_options", "issuer, clientId and redirectUri are required");
+        this.issuer = normalizeIssuer(options.issuer, options.allowInsecureIssuer);
+        this.storage = options.storage ?? defaultStorage("localStorage");
+        this.transient = options.transientStorage ?? defaultStorage("sessionStorage");
+        this.fetcher = options.fetch ?? fetch.bind(globalThis);
+        this.key = `9in:${this.issuer}:${options.clientId}`;
+    }
+    navigate(url) {
+        if (this.options.navigate)
+            this.options.navigate(url);
+        else
+            window.location.assign(url);
+    }
+    /** Builds the authorization URL and stores the PKCE verifier; `login()` navigates to it. */
+    async buildLoginUrl(options = {}) {
+        const config = await discover(this.issuer, this.fetcher);
+        const pending = { state: randomString(16), nonce: randomString(16), verifier: randomString(48), returnTo: options.returnTo };
+        this.transient.setItem(`${this.key}:pending`, JSON.stringify(pending));
+        const url = new URL(config.authorization_endpoint);
+        const params = {
+            response_type: "code",
+            client_id: this.options.clientId,
+            redirect_uri: this.options.redirectUri,
+            scope: this.options.scope ?? "openid profile email offline_access",
+            state: pending.state,
+            nonce: pending.nonce,
+            code_challenge: base64UrlEncode(await sha256(pending.verifier)),
+            code_challenge_method: "S256",
+            ...(this.options.audience ? { audience: this.options.audience } : {}),
+            ...(this.options.locale ? { ui_locales: this.options.locale } : {}),
+            ...(options.loginHint ? { login_hint: options.loginHint } : {}),
+            ...(options.screen === "signup" ? { prompt: "create" } : options.prompt ? { prompt: options.prompt } : {}),
+            ...options.params,
+        };
+        for (const [k, v] of Object.entries(params))
+            url.searchParams.set(k, v);
+        return url.toString();
+    }
+    /** Redirects to the hosted login page. */
+    async login(options = {}) {
+        this.navigate(await this.buildLoginUrl(options));
+    }
+    /** Opens the sign-up form directly. */
+    async signup(options = {}) {
+        return this.login({ ...options, screen: "signup" });
+    }
+    /**
+     * Completes sign-in on the callback page: checks state, exchanges the code with the PKCE
+     * verifier and stores the tokens. Removes the code from the address bar.
+     */
+    async handleRedirect(url = typeof window !== "undefined" ? window.location.href : "") {
+        const current = new URL(url);
+        const params = current.searchParams;
+        const raw = this.transient.getItem(`${this.key}:pending`);
+        this.transient.removeItem(`${this.key}:pending`);
+        if (params.get("error"))
+            throw new NineError(params.get("error"), params.get("error_description") ?? undefined);
+        const code = params.get("code");
+        if (!code)
+            throw new NineError("missing_code", "no authorization code in the URL");
+        if (!raw)
+            throw new NineError("invalid_state", "no login in progress (opened in another tab?)");
+        const pending = JSON.parse(raw);
+        if (params.get("state") !== pending.state)
+            throw new NineError("invalid_state", "state mismatch");
+        const iss = params.get("iss");
+        if (iss && iss.replace(/\/$/, "") !== this.issuer && !(await this.sameIssuer(iss)))
+            throw new NineError("invalid_issuer", `unexpected issuer ${iss}`);
+        const config = await discover(this.issuer, this.fetcher);
+        const tokens = await postForm(config.token_endpoint, { grant_type: "authorization_code", code, redirect_uri: this.options.redirectUri, client_id: this.options.clientId, code_verifier: pending.verifier }, {}, this.fetcher);
+        if (typeof tokens.id_token === "string") {
+            // The ID token came straight from the token endpoint over TLS (OIDC Core 3.1.3.7):
+            // its claims are checked; the signature check is for servers (verifyAccessToken).
+            // Checked before anything is stored, so a refused sign-in leaves no tokens behind.
+            let payload;
+            try {
+                payload = decodeJwt(tokens.id_token).payload;
+            }
+            catch {
+                throw new NineError("invalid_id_token", "malformed ID token");
+            }
+            const aud = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+            if (!aud.includes(this.options.clientId))
+                throw new NineError("invalid_id_token", "audience mismatch");
+            if (payload.nonce !== pending.nonce)
+                throw new NineError("invalid_id_token", "nonce mismatch");
+        }
+        this.store(tokens);
+        if (typeof window !== "undefined" && window.history && url === window.location.href) {
+            for (const p of ["code", "state", "iss", "session_state"])
+                current.searchParams.delete(p);
+            window.history.replaceState(window.history.state, "", current.pathname + current.search + current.hash);
+        }
+        return { user: (await this.getUser()), returnTo: pending.returnTo };
+    }
+    async sameIssuer(iss) {
+        const config = await discover(this.issuer, this.fetcher);
+        return config.issuer.replace(/\/$/, "") === iss.replace(/\/$/, "");
+    }
+    store(tokens, previous) {
+        const set = {
+            accessToken: String(tokens.access_token),
+            idToken: typeof tokens.id_token === "string" ? tokens.id_token : (previous?.idToken ?? null),
+            refreshToken: typeof tokens.refresh_token === "string" ? tokens.refresh_token : (previous?.refreshToken ?? null),
+            expiresAt: Date.now() + Number(tokens.expires_in ?? 3600) * 1000,
+            scope: String(tokens.scope ?? previous?.scope ?? ""),
+        };
+        this.storage.setItem(`${this.key}:tokens`, JSON.stringify(set));
+        return set;
+    }
+    /** Stored tokens (possibly expired). */
+    getTokens() {
+        const raw = this.storage.getItem(`${this.key}:tokens`);
+        if (!raw)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** True when there is a usable access token or a refresh token. */
+    isAuthenticated() {
+        const t = this.getTokens();
+        return !!t && (t.expiresAt > Date.now() || !!t.refreshToken);
+    }
+    /** Claims of the signed-in user from the ID token, or null. */
+    async getUser() {
+        const t = this.getTokens();
+        if (!t?.idToken)
+            return null;
+        return decodeJwt(t.idToken).payload;
+    }
+    /** Fresh claims from the userinfo endpoint. */
+    async fetchUserInfo() {
+        const config = await discover(this.issuer, this.fetcher);
+        const res = await this.fetcher(config.userinfo_endpoint, { headers: { Authorization: `Bearer ${await this.getAccessToken()}` } });
+        if (!res.ok)
+            throw new NineError("userinfo_failed", `HTTP ${res.status}`, res.status);
+        return (await res.json());
+    }
+    /**
+     * A valid access token, refreshed (with rotation) when it expires within a minute.
+     * Concurrent callers share one refresh. Throws `login_required` when signed out.
+     */
+    async getAccessToken() {
+        const t = this.getTokens();
+        if (t && t.expiresAt - 60_000 > Date.now())
+            return t.accessToken;
+        if (!t?.refreshToken)
+            throw new NineError("login_required");
+        this.refreshing ??= this.refresh(t).finally(() => {
+            this.refreshing = null;
+        });
+        const next = await this.refreshing;
+        if (!next)
+            throw new NineError("login_required");
+        return next.accessToken;
+    }
+    async refresh(current) {
+        const config = await discover(this.issuer, this.fetcher);
+        try {
+            const tokens = await postForm(config.token_endpoint, { grant_type: "refresh_token", refresh_token: current.refreshToken, client_id: this.options.clientId }, {}, this.fetcher);
+            return this.store(tokens, current);
+        }
+        catch (error) {
+            if (error instanceof NineError && error.code === "invalid_grant") {
+                this.storage.removeItem(`${this.key}:tokens`);
+                return null;
+            }
+            throw error;
+        }
+    }
+    /** fetch() with the access token attached. */
+    async fetch(input, init = {}) {
+        const headers = new Headers(init.headers);
+        headers.set("Authorization", `Bearer ${await this.getAccessToken()}`);
+        return this.fetcher(input, { ...init, headers });
+    }
+    /** Clears local tokens, revokes the refresh token and ends the 9in session. */
+    async logout(options = {}) {
+        const t = this.getTokens();
+        this.storage.removeItem(`${this.key}:tokens`);
+        const config = await discover(this.issuer, this.fetcher);
+        if (t?.refreshToken && config.revocation_endpoint) {
+            await postForm(config.revocation_endpoint, { token: t.refreshToken, token_type_hint: "refresh_token", client_id: this.options.clientId }, {}, this.fetcher).catch(() => undefined);
+        }
+        if (options.local)
+            return;
+        const url = new URL(config.end_session_endpoint ?? `${this.issuer}/oauth/logout`);
+        url.searchParams.set("client_id", this.options.clientId);
+        if (t?.idToken)
+            url.searchParams.set("id_token_hint", t.idToken);
+        if (options.returnTo)
+            url.searchParams.set("post_logout_redirect_uri", options.returnTo);
+        this.navigate(url.toString());
+    }
+}