okengine 0.18.4 → 0.19.0

package/src/client/auth/denials.ts

@@ -0,0 +1,99 @@
+/**
+ * Auth / gate denial narrowers — envelope values, not throws.
+ *
+ * @module
+ */
+
+/** Common auth Flow error codes (server `fail` codes). */
+export const AUTH_ERROR_CODES = {
+  AuthFailed: "AuthFailed",
+  AuthRateLimited: "AuthRateLimited",
+  Unauthorized: "Unauthorized",
+  Forbidden: "Forbidden",
+} as const;
+
+function errorCode(error: unknown): string | undefined {
+  if (error === null || typeof error !== "object") return undefined;
+  if (!("code" in error)) return undefined;
+  const code = (error as { code: unknown }).code;
+  return typeof code === "string" ? code : undefined;
+}
+
+function errorReason(error: unknown): string | undefined {
+  if (error === null || typeof error !== "object") return undefined;
+  const data = (error as { data?: unknown }).data;
+  if (data === null || typeof data !== "object") return undefined;
+  const reason = (data as { reason?: unknown }).reason;
+  return typeof reason === "string" ? reason : undefined;
+}
+
+/** True when the envelope error is `Unauthorized`. */
+export function isUnauthorized(error: unknown): boolean {
+  return errorCode(error) === AUTH_ERROR_CODES.Unauthorized;
+}
+
+/** True when the envelope error is `Forbidden` (policy / CSRF / etc.). */
+export function isForbidden(error: unknown): boolean {
+  return errorCode(error) === AUTH_ERROR_CODES.Forbidden;
+}
+
+/** True when the envelope error is `AuthRateLimited` or HTTP `RateLimited`. */
+export function isAuthRateLimited(error: unknown): boolean {
+  const code = errorCode(error);
+  return code === AUTH_ERROR_CODES.AuthRateLimited || code === "RateLimited";
+}
+
+/** True when Forbidden reason is CSRF. */
+export function isCsrf(error: unknown): boolean {
+  return isForbidden(error) && errorReason(error) === "csrf";
+}
+
+/**
+ * Best-effort scopes named in a Forbidden envelope (`gate` / `reason` / `missing`).
+ * UI hint only — Gate on Flows remains the security boundary.
+ *
+ * @param error - Envelope error
+ */
+export function forbiddenScopes(error: unknown): readonly string[] {
+  if (!isForbidden(error)) return [];
+  if (error === null || typeof error !== "object") return [];
+  const data = (error as { data?: unknown }).data;
+  if (data === null || typeof data !== "object") return [];
+  const bag = data as Record<string, unknown>;
+  if (Array.isArray(bag.missing)) {
+    return bag.missing.filter((s): s is string => typeof s === "string");
+  }
+  if (typeof bag.gate === "string" && bag.gate.includes(":")) return [bag.gate];
+  if (typeof bag.reason === "string" && bag.reason.includes(":")) return [bag.reason];
+  return [];
+}
+
+/** True when sign-in data asks for a second factor. */
+export function isTwoFactorRequired(data: unknown): data is {
+  readonly twoFactorRequired: true;
+  readonly challengeId: string;
+  readonly method: string;
+  readonly userId: string;
+} {
+  return (
+    data !== null &&
+    typeof data === "object" &&
+    (data as { twoFactorRequired?: unknown }).twoFactorRequired === true &&
+    typeof (data as { challengeId?: unknown }).challengeId === "string"
+  );
+}
+
+/** True when data looks like issued session tokens. */
+export function isSessionTokens(data: unknown): data is {
+  readonly accessToken: string;
+  readonly refreshToken: string;
+  readonly accessExpiresAt?: number;
+  readonly userId?: string;
+} {
+  return (
+    data !== null &&
+    typeof data === "object" &&
+    typeof (data as { accessToken?: unknown }).accessToken === "string" &&
+    typeof (data as { refreshToken?: unknown }).refreshToken === "string"
+  );
+}

package/src/client/auth/session.ts

@@ -0,0 +1,283 @@
+/**
+ * Session token bag — memory / Storage persist with subscribe.
+ *
+ * @module
+ */
+
+/** Tokens written into a session store. */
+export interface SessionTokens {
+  readonly accessToken: string;
+  readonly refreshToken: string;
+  readonly accessExpiresAt?: number;
+  readonly userId?: string;
+  readonly scopes?: readonly string[];
+  readonly tenantId?: string | null;
+}
+
+/** Snapshot of identity for UI (from `auth.me` / sign-in). */
+export interface SessionUser {
+  readonly userId: string;
+  readonly email?: string;
+  readonly name?: string;
+  readonly emailVerified?: boolean;
+  readonly scopes: readonly string[];
+  readonly tenantId: string | null;
+  readonly apiKeyId: string | null;
+  readonly sessionFresh?: boolean;
+}
+
+/** Listener notified on session mutations. */
+export type SessionListener = () => void;
+
+/** In-memory / persisted session token bag for Bearer `createClient` wiring. */
+export interface MemorySession {
+  accessToken: string | null;
+  refreshToken: string | null;
+  accessExpiresAt: number | null;
+  userId: string | null;
+  scopes: readonly string[];
+  tenantId: string | null;
+  user: SessionUser | null;
+  set(tokens: SessionTokens): void;
+  setUser(user: SessionUser | null): void;
+  clear(): void;
+  /** Wire into `createClient` `auth.getToken`. */
+  getToken(): string | null;
+  /** Subscribe to mutations; returns unsubscribe. */
+  subscribe(listener: SessionListener): () => void;
+  /**
+   * Wire into `createClient` `auth.refresh` — calls the refresh Flow via the client.
+   *
+   * @param api - Client with `auth.refresh` route
+   */
+  refresh(api: {
+    auth: {
+      refresh: (input: { refreshToken: string }) => Promise<{
+        data: {
+          accessToken: string;
+          refreshToken: string;
+          accessExpiresAt?: number;
+          userId?: string;
+        } | null;
+        error: unknown;
+      }>;
+    };
+  }): Promise<string | null>;
+}
+
+/** Options for {@link memorySession} / {@link persistSession}. */
+export interface MemorySessionOptions {
+  /**
+   * Web Storage backend. Prefer `sessionStorage` over `localStorage`
+   * (XSS can still steal; `localStorage` survives tabs — explicit opt-in only).
+   */
+  readonly storage?: Storage;
+  /** Storage key (default `oke.session`). */
+  readonly key?: string;
+}
+
+const DEFAULT_KEY = "oke.session";
+
+interface StoredBag {
+  readonly accessToken: string;
+  readonly refreshToken: string;
+  readonly accessExpiresAt: number | null;
+  readonly userId: string | null;
+  readonly scopes: readonly string[];
+  readonly tenantId: string | null;
+  readonly user: SessionUser | null;
+}
+
+/**
+ * Create an in-memory session helper for Bearer `createClient` wiring.
+ *
+ * @param options - Optional Storage persist (memory when omitted)
+ */
+export function memorySession(options?: MemorySessionOptions): MemorySession {
+  const storage = options?.storage;
+  const key = options?.key ?? DEFAULT_KEY;
+  const listeners = new Set<SessionListener>();
+
+  const state: {
+    accessToken: string | null;
+    refreshToken: string | null;
+    accessExpiresAt: number | null;
+    userId: string | null;
+    scopes: readonly string[];
+    tenantId: string | null;
+    user: SessionUser | null;
+  } = {
+    accessToken: null,
+    refreshToken: null,
+    accessExpiresAt: null,
+    userId: null,
+    scopes: [],
+    tenantId: null,
+    user: null,
+  };
+
+  if (storage) {
+    try {
+      const raw = storage.getItem(key);
+      if (raw) {
+        const parsed = JSON.parse(raw) as StoredBag;
+        state.accessToken = parsed.accessToken ?? null;
+        state.refreshToken = parsed.refreshToken ?? null;
+        state.accessExpiresAt = parsed.accessExpiresAt ?? null;
+        state.userId = parsed.userId ?? null;
+        state.scopes = parsed.scopes ?? [];
+        state.tenantId = parsed.tenantId ?? null;
+        state.user = parsed.user ?? null;
+      }
+    } catch {
+      /* ignore corrupt storage */
+    }
+  }
+
+  function persist(): void {
+    if (!storage) return;
+    if (!state.accessToken || !state.refreshToken) {
+      storage.removeItem(key);
+      return;
+    }
+    const bag: StoredBag = {
+      accessToken: state.accessToken,
+      refreshToken: state.refreshToken,
+      accessExpiresAt: state.accessExpiresAt,
+      userId: state.userId,
+      scopes: state.scopes,
+      tenantId: state.tenantId,
+      user: state.user,
+    };
+    storage.setItem(key, JSON.stringify(bag));
+  }
+
+  function notify(): void {
+    for (const l of listeners) l();
+  }
+
+  return {
+    get accessToken() {
+      return state.accessToken;
+    },
+    set accessToken(v) {
+      state.accessToken = v;
+      persist();
+      notify();
+    },
+    get refreshToken() {
+      return state.refreshToken;
+    },
+    set refreshToken(v) {
+      state.refreshToken = v;
+      persist();
+      notify();
+    },
+    get accessExpiresAt() {
+      return state.accessExpiresAt;
+    },
+    set accessExpiresAt(v) {
+      state.accessExpiresAt = v;
+      persist();
+      notify();
+    },
+    get userId() {
+      return state.userId;
+    },
+    set userId(v) {
+      state.userId = v;
+      persist();
+      notify();
+    },
+    get scopes() {
+      return state.scopes;
+    },
+    set scopes(v) {
+      state.scopes = v;
+      persist();
+      notify();
+    },
+    get tenantId() {
+      return state.tenantId;
+    },
+    set tenantId(v) {
+      state.tenantId = v;
+      persist();
+      notify();
+    },
+    get user() {
+      return state.user;
+    },
+    set(tokens) {
+      state.accessToken = tokens.accessToken;
+      state.refreshToken = tokens.refreshToken;
+      state.accessExpiresAt = tokens.accessExpiresAt ?? null;
+      state.userId = tokens.userId ?? null;
+      if (tokens.scopes) state.scopes = tokens.scopes;
+      if (tokens.tenantId !== undefined) state.tenantId = tokens.tenantId;
+      persist();
+      notify();
+    },
+    setUser(user) {
+      state.user = user;
+      if (user) {
+        state.userId = user.userId;
+        state.scopes = user.scopes;
+        state.tenantId = user.tenantId;
+      }
+      persist();
+      notify();
+    },
+    clear() {
+      state.accessToken = null;
+      state.refreshToken = null;
+      state.accessExpiresAt = null;
+      state.userId = null;
+      state.scopes = [];
+      state.tenantId = null;
+      state.user = null;
+      persist();
+      notify();
+    },
+    getToken() {
+      return state.accessToken;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    async refresh(api) {
+      if (!state.refreshToken) return null;
+      const { data, error } = await api.auth.refresh({ refreshToken: state.refreshToken });
+      if (error || !data) {
+        state.accessToken = null;
+        persist();
+        notify();
+        return null;
+      }
+      state.accessToken = data.accessToken;
+      state.refreshToken = data.refreshToken;
+      state.accessExpiresAt = data.accessExpiresAt ?? null;
+      if (data.userId) state.userId = data.userId;
+      persist();
+      notify();
+      return data.accessToken;
+    },
+  };
+}
+
+/**
+ * Bearer session persisted to Storage.
+ *
+ * **Security:** XSS can read Storage. Prefer cookie mode or memory.
+ * Use `sessionStorage` before `localStorage`; `localStorage` is an explicit
+ * multi-tab convenience tradeoff — never the silent default.
+ *
+ * @param storage - `sessionStorage` or `localStorage`
+ * @param key - Optional storage key
+ */
+export function persistSession(storage: Storage, key?: string): MemorySession {
+  return memorySession({ storage, key });
+}

package/src/client/auth.test.ts

@@ -0,0 +1,251 @@
+/**
+ * Auth helpers tests — session subscribe, createAuthClient secure defaults.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  createAuthClient,
+  isForbidden,
+  isSessionTokens,
+  isTwoFactorRequired,
+  isUnauthorized,
+  memorySession,
+  persistSession,
+} from "./auth.ts";
+
+describe("memorySession", () => {
+  test("subscribe notifies on set and clear", () => {
+    const s = memorySession();
+    let n = 0;
+    const unsub = s.subscribe(() => {
+      n += 1;
+    });
+    s.set({ accessToken: "a", refreshToken: "r", userId: "u1" });
+    expect(n).toBe(1);
+    s.clear();
+    expect(n).toBe(2);
+    unsub();
+    s.set({ accessToken: "a2", refreshToken: "r2" });
+    expect(n).toBe(2);
+  });
+
+  test("persistSession round-trips via Storage", () => {
+    const store = new Map<string, string>();
+    const storage: Storage = {
+      get length() {
+        return store.size;
+      },
+      clear() {
+        store.clear();
+      },
+      getItem(k) {
+        return store.get(k) ?? null;
+      },
+      key() {
+        return null;
+      },
+      removeItem(k) {
+        store.delete(k);
+      },
+      setItem(k, v) {
+        store.set(k, v);
+      },
+    };
+    const a = persistSession(storage);
+    a.set({ accessToken: "tok", refreshToken: "ref", userId: "u" });
+    const b = persistSession(storage);
+    expect(b.getToken()).toBe("tok");
+    expect(b.refreshToken).toBe("ref");
+  });
+});
+
+describe("denials", () => {
+  test("narrowers", () => {
+    expect(isUnauthorized({ code: "Unauthorized", data: {} })).toBe(true);
+    expect(isForbidden({ code: "Forbidden", data: { reason: "csrf" } })).toBe(true);
+    expect(
+      isTwoFactorRequired({
+        twoFactorRequired: true,
+        challengeId: "c",
+        method: "totp",
+        userId: "u",
+      }),
+    ).toBe(true);
+    expect(isSessionTokens({ accessToken: "a", refreshToken: "r" })).toBe(true);
+  });
+});
+
+describe("createAuthClient", () => {
+  test("refuses cookie mode with localStorage persist", () => {
+    expect(() =>
+      createAuthClient(
+        { auth: {} },
+        { mode: "cookie", persist: "localStorage", csrfConfigured: true },
+      ),
+    ).toThrow(/cannot persist/);
+  });
+
+  test("warns when cookie mode without csrfConfigured", () => {
+    const warnings: string[] = [];
+    createAuthClient(
+      { auth: {} },
+      {
+        mode: "cookie",
+        env: { warn: (m) => warnings.push(m) },
+      },
+    );
+    expect(warnings.some((w) => w.includes("csrf"))).toBe(true);
+  });
+
+  test("signIn.email sets session and hasScope is UI-only from me", async () => {
+    const api = {
+      auth: {
+        signInEmail: async () => ({
+          data: {
+            accessToken: "a",
+            refreshToken: "r",
+            accessExpiresAt: Date.now() + 60_000,
+            userId: "u1",
+          },
+          error: null,
+        }),
+        me: async () => ({
+          data: {
+            userId: "u1",
+            email: "a@b.co",
+            name: "A",
+            emailVerified: true,
+            scopes: ["orders:write"],
+            tenantId: null,
+            apiKeyId: null,
+          },
+          error: null,
+        }),
+        revoke: async () => ({ data: { ok: true }, error: null }),
+      },
+    };
+    const auth = createAuthClient(api, { csrfConfigured: true });
+    const result = await auth.signIn.email({ email: "a@b.co", password: "x" });
+    expect(result.ok).toBe(true);
+    expect(auth.hasScope("orders:write")).toBe(true);
+    expect(auth.can("orders:write")).toBe(true);
+    expect(auth.hasScope("admin")).toBe(false);
+    await auth.signOut();
+    expect(auth.session.getToken()).toBeNull();
+  });
+
+  test("twoFactorRequired discrimination", async () => {
+    const api = {
+      auth: {
+        signInEmail: async () => ({
+          data: {
+            twoFactorRequired: true as const,
+            challengeId: "ch1",
+            method: "totp",
+            userId: "u1",
+          },
+          error: null,
+        }),
+      },
+    };
+    const auth = createAuthClient(api);
+    const result = await auth.signIn.email({ email: "a@b.co", password: "x" });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.twoFactor?.challengeId).toBe("ch1");
+  });
+
+  test("setTenant adds header via clientOptions", () => {
+    const auth = createAuthClient({ auth: {} });
+    auth.setTenant("t_1");
+    const headers = auth.clientOptions.headers?.();
+    expect(headers?.["x-oke-tenant"]).toBe("t_1");
+  });
+
+  test("authorize reports allowed / denied / unauthenticated", async () => {
+    const api = {
+      auth: {
+        signInEmail: async () => ({
+          data: {
+            accessToken: "a",
+            refreshToken: "r",
+            userId: "u1",
+          },
+          error: null,
+        }),
+        me: async () => ({
+          data: {
+            userId: "u1",
+            email: "a@b.co",
+            name: "A",
+            scopes: ["notes:write"],
+            tenantId: null,
+            apiKeyId: null,
+          },
+          error: null,
+        }),
+      },
+    };
+    const auth = createAuthClient(api);
+    expect(auth.authorize({ all: ["notes:write"] }).status).toBe("unauthenticated");
+    await auth.signIn.email({ email: "a@b.co", password: "x" });
+    expect(auth.authorize({ all: ["notes:write"] }).status).toBe("allowed");
+    const denied = auth.authorize({ all: ["notes:write", "admin"] });
+    expect(denied.status).toBe("denied");
+    if (denied.status === "denied") expect(denied.missing).toEqual(["admin"]);
+    expect(auth.authorize({ any: ["admin", "notes:write"] }).status).toBe("allowed");
+  });
+});
+
+describe("tokenFromRequestCookies", () => {
+  test("parses access cookie from header / Request", async () => {
+    const { tokenFromRequestCookies } = await import("./auth.ts");
+    const header = "oke.session_token=abc%20123; other=1";
+    expect(tokenFromRequestCookies(header)).toBe("abc 123");
+    expect(tokenFromRequestCookies(new Headers({ cookie: header }))).toBe("abc 123");
+    expect(
+      tokenFromRequestCookies(new Request("http://localhost", { headers: { cookie: header } })),
+    ).toBe("abc 123");
+    expect(tokenFromRequestCookies("")).toBeNull();
+  });
+});
+
+describe("createClient session auth", () => {
+  test("attaches api.auth and preserves auth unit flows", async () => {
+    const { createClient } = await import("./create-with-session.ts");
+    const calls: string[] = [];
+    const api = createClient("http://example.test", {
+      $routes: {
+        auth: {
+          me: { method: "GET", path: "/auth/me" },
+        },
+      },
+      auth: { mode: "bearer", csrfConfigured: true },
+      fetch: async (input) => {
+        calls.push(String(input));
+        return new Response(
+          JSON.stringify({
+            data: {
+              userId: "u1",
+              email: "a@b.co",
+              name: "A",
+              scopes: ["notes:write"],
+              tenantId: null,
+              apiKeyId: null,
+            },
+            error: null,
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      },
+    });
+    expect(api.auth).toBeDefined();
+    expect(typeof api.auth?.authorize).toBe("function");
+    // Runtime merge keeps unit Flows (`me`) on the AuthClient proxy.
+    expect(
+      api.auth && "me" in api.auth && typeof (api.auth as { me: unknown }).me === "function",
+    ).toBe(true);
+    const user = await api.auth!.getSession();
+    expect(user?.scopes).toEqual(["notes:write"]);
+    expect(calls.some((u) => u.includes("/auth/me"))).toBe(true);
+  });
+});