@riboseinc/ribose-identity-client 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@riboseinc/ribose-identity-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "vitest run --dir test"
+  },
+  "devDependencies": {
+    "@riboseinc/ribose-identity-kernel": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,259 @@
+/**
+ * @riboseinc/ribose-identity-client — the browser-only relying-party SDK for a
+ * Ribose ID instance (any OIDC provider with the same profile:
+ * authorization code + PKCE S256, ES256 ID tokens, opaque reference
+ * tokens).
+ *
+ * The Auth0/Clerk shape, ~150 lines, ZERO dependencies, pure browser:
+ * `signIn()` sends the user's browser to /authorize with a freshly
+ * generated PKCE pair; `handleCallback()` verifies state, exchanges
+ * the code at /token, and decodes the ID-token payload; `signOut()`
+ * drops the local state. The PKCE verifier and state live in
+ * sessionStorage, namespaced per issuer + client_id, so several RPs
+ * can share one origin without colliding.
+ *
+ * The SDK never verifies the ID-token SIGNATURE — that is a
+ * server-side job with the provider's JWKS (see the instance's
+ * relying-party integration manual). It returns the decoded payload
+ * for the client-side claims a SPA may want (nonce, email), plus the
+ * raw tokens for the RP's own verifier.
+ */
+
+export interface RPConfig {
+  /** The instance's issuer URL, exactly as discovery advertises it. */
+  issuer: string;
+  clientId: string;
+  redirectUri: string;
+}
+
+export interface SignInOptions {
+  /** Bind the callback to this request; generated when omitted. */
+  state?: string;
+  /** Sent through to the ID token; generated when omitted. */
+  nonce?: string;
+  /** `openid email` when omitted (everything else the instance ignores). */
+  scope?: string;
+}
+
+/** What `handleCallback()` resolves with: the grant plus the decoded
+ *  ID-token payload (signature verification stays the RP's job). */
+export interface CallbackResult {
+  idToken: string;
+  accessToken: string;
+  refreshToken: string;
+  claims: Record<string, unknown>;
+}
+
+export interface RelyingParty {
+  signIn(options?: SignInOptions): Promise<void>;
+  handleCallback(): Promise<CallbackResult>;
+  signOut(): void;
+}
+
+export function configure(config: RPConfig): RelyingParty {
+  return new BrowserRelyingParty(config);
+}
+
+// ── pure helpers (exported for reuse and for specs) ─────────────────
+
+/** The issuer with any trailing slash removed — endpoint URLs hang
+ *  off this base. */
+export function issuerBase(issuer: string): string {
+  return issuer.replace(/\/+$/, "");
+}
+
+/** RFC 7636 S256 challenge derivation over the Web Crypto API — the
+ *  browser twin of the OP kernel's `pkceChallenge` (SHA-256,
+ *  base64url, no padding). */
+export async function pkceChallenge(verifier: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(verifier),
+  );
+  return base64url(new Uint8Array(digest));
+}
+
+/** A fresh PKCE pair: 32 random bytes of verifier (43 unreserved
+ *  characters — inside the RFC 7636 43–128 band) plus its challenge. */
+export async function createPkcePair(): Promise<{
+  verifier: string;
+  challenge: string;
+}> {
+  const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
+  return { verifier, challenge: await pkceChallenge(verifier) };
+}
+
+/** A random unguessable value (state/nonce material). */
+export function randomToken(byteLength = 24): string {
+  return base64url(crypto.getRandomValues(new Uint8Array(byteLength)));
+}
+
+/** base64url (RFC 4648 §5): URL-safe alphabet, no padding. */
+export function base64url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+
+export interface AuthorizeUrlParams {
+  codeChallenge: string;
+  state: string;
+  nonce?: string;
+  scope?: string;
+}
+
+/** The exact /authorize query the OP validates: code + PKCE S256,
+ *  always with state and (by default) a nonce. Pure — no browser. */
+export function buildAuthorizeUrl(
+  config: RPConfig,
+  params: AuthorizeUrlParams,
+): string {
+  const url = new URL(`${issuerBase(config.issuer)}/authorize`);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", config.clientId);
+  url.searchParams.set("redirect_uri", config.redirectUri);
+  url.searchParams.set("code_challenge", params.codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", params.state);
+  if (params.nonce !== undefined) url.searchParams.set("nonce", params.nonce);
+  url.searchParams.set("scope", params.scope ?? "openid email");
+  return url.toString();
+}
+
+export interface CallbackQuery {
+  code: string | undefined;
+  state: string | undefined;
+  error: string | undefined;
+}
+
+/** Reads code/state/error off a callback URL. Pure — no browser. */
+export function parseCallback(url: string): CallbackQuery {
+  const params = new URL(url).searchParams;
+  const pick = (key: string): string | undefined => {
+    const value = params.get(key);
+    return value === null ? undefined : value;
+  };
+  return { code: pick("code"), state: pick("state"), error: pick("error") };
+}
+
+/** Decodes (does NOT verify) the ID token's payload segment. */
+export function decodeIdTokenPayload(
+  idToken: string,
+): Record<string, unknown> {
+  const parts = idToken.split(".");
+  if (parts.length !== 3) {
+    throw new Error("not a JWS compact serialization (three parts expected)");
+  }
+  const base64 = parts[1]!.replaceAll("-", "+").replaceAll("_", "/");
+  const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
+  const bytes = Uint8Array.from(atob(padded), (char) => char.charCodeAt(0));
+  return JSON.parse(new TextDecoder().decode(bytes)) as Record<string, unknown>;
+}
+
+// ── the browser implementation ──────────────────────────────────────
+
+/** One sessionStorage namespace per issuer + client_id, so multiple
+ *  RPs on one origin never read each other's sign-in state. */
+function sessionKeys(config: RPConfig): Record<"verifier" | "state" | "nonce", string> {
+  const scope = `ribose-id.rp:${issuerBase(config.issuer)}:${config.clientId}`;
+  return {
+    verifier: `${scope}.verifier`,
+    state: `${scope}.state`,
+    nonce: `${scope}.nonce`,
+  };
+}
+
+class BrowserRelyingParty implements RelyingParty {
+  private readonly keys: ReturnType<typeof sessionKeys>;
+
+  constructor(private readonly config: RPConfig) {
+    this.keys = sessionKeys(config);
+  }
+
+  async signIn(options: SignInOptions = {}): Promise<void> {
+    const pkce = await createPkcePair();
+    const state = options.state ?? randomToken();
+    const nonce = options.nonce ?? randomToken();
+    const storage = window.sessionStorage;
+    storage.setItem(this.keys.verifier, pkce.verifier);
+    storage.setItem(this.keys.state, state);
+    storage.setItem(this.keys.nonce, nonce);
+    window.location.assign(
+      buildAuthorizeUrl(this.config, {
+        codeChallenge: pkce.challenge,
+        state,
+        nonce,
+        scope: options.scope ?? "openid",
+      }),
+    );
+  }
+
+  async handleCallback(): Promise<CallbackResult> {
+    const callback = parseCallback(window.location.href);
+    if (callback.error !== undefined) {
+      throw new Error(`authorization failed: ${callback.error}`);
+    }
+    if (callback.code === undefined) {
+      throw new Error("no authorization code in the callback URL");
+    }
+    const state = window.sessionStorage.getItem(this.keys.state);
+    if (
+      callback.state === undefined ||
+      state === null ||
+      callback.state !== state
+    ) {
+      throw new Error(
+        "state mismatch — the callback does not belong to this browser's sign-in",
+      );
+    }
+    const verifier = window.sessionStorage.getItem(this.keys.verifier);
+    if (verifier === null) {
+      throw new Error("no sign-in in progress — call signIn() first");
+    }
+    const response = await fetch(`${issuerBase(this.config.issuer)}/token`, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: this.config.clientId,
+        code: callback.code,
+        redirect_uri: this.config.redirectUri,
+        code_verifier: verifier,
+      }),
+    });
+    const grant = (await response.json().catch(() => null)) as {
+      id_token?: string;
+      access_token?: string;
+      refresh_token?: string;
+      error?: string;
+      error_description?: string;
+    } | null;
+    if (
+      !response.ok ||
+      grant === null ||
+      grant.id_token === undefined ||
+      grant.access_token === undefined
+    ) {
+      const reason =
+        grant?.error_description ??
+        grant?.error ??
+        `HTTP ${String(response.status)}`;
+      throw new Error(`token exchange failed: ${reason}`);
+    }
+    const result: CallbackResult = {
+      idToken: grant.id_token,
+      accessToken: grant.access_token,
+      refreshToken: grant.refresh_token ?? "",
+      claims: decodeIdTokenPayload(grant.id_token),
+    };
+    this.signOut();
+    return result;
+  }
+
+  signOut(): void {
+    const storage = window.sessionStorage;
+    for (const key of [this.keys.verifier, this.keys.state, this.keys.nonce]) {
+      storage.removeItem(key);
+    }
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.