@cplieger/access 0.0.0-stage → 1.0.0-dev.10

package/src/oidc.ts

@@ -0,0 +1,77 @@
+import type { ApiResult } from "@cplieger/reactive/fetch";
+import type { AuthClient } from "./client.js";
+import { knownCode } from "./wire.js";
+import type { AuthCode, MeResponse, OIDCStartResponse, PendingLinkResponse } from "./wire.js";
+
+/**
+ * The URL that starts an OIDC sign-in, for a plain navigation or a link: GET
+ * {oidcPrefix}/start/signin, with redirect, the app's relative return path, when given. The
+ * server lands on "/" for a redirect it refuses.
+ */
+export function oidcSignInURL(c: AuthClient, redirect?: string): string {
+  const start = `${c.oidcPrefix}/start/signin`;
+  return redirect === undefined || redirect === ""
+    ? start
+    : `${start}?${new URLSearchParams({ redirect }).toString()}`;
+}
+
+/**
+ * Link and step-up POST same-origin first, then navigate to the returned URL. redirect is the
+ * app's relative return path, at most 512 bytes (oidc.MaxRedirectBytes); the server refuses a
+ * longer one.
+ */
+export function startOIDC(
+  c: AuthClient,
+  intent: "link" | "stepup",
+  redirect?: string,
+): Promise<ApiResult<OIDCStartResponse>> {
+  const r = redirect === undefined ? {} : { redirect };
+  return intent === "link" ? c.oidcStartLink(r) : c.oidcStartStepUp(r);
+}
+
+export type OIDCReturn =
+  | { readonly kind: "none" }
+  | { readonly kind: "not_linked" }
+  | { readonly kind: "linked" }
+  | { readonly kind: "stepped_up" }
+  | { readonly kind: "error"; readonly code: AuthCode | undefined };
+
+/**
+ * Reads the callback's markers from search (location.search). An auth_error outside the
+ * AuthCode union gives code undefined, and an auth_error beside an oidc marker is the error.
+ * A marker is a hint any link can carry: the page never dispatches on it without the user's
+ * click, and a lasting continuation is bound to same-origin state, continuation.put's nonce,
+ * never to URL arguments alone.
+ */
+export function readOIDCReturn(search: string): OIDCReturn {
+  const q = new URLSearchParams(search);
+  const errors = q.getAll("auth_error");
+  if (errors.length > 0) {
+    const only = errors.length === 1 ? errors[0] : undefined;
+    return { kind: "error", code: only === undefined ? undefined : knownCode(only) };
+  }
+  const markers = q.getAll("oidc");
+  if (markers.length !== 1) {
+    return { kind: "none" };
+  }
+  switch (markers[0]) {
+    case "not_linked":
+      return { kind: "not_linked" };
+    case "linked":
+      return { kind: "linked" };
+    case "stepped_up":
+      return { kind: "stepped_up" };
+    default:
+      return { kind: "none" };
+  }
+}
+
+/** The IdP identity a not-linked OIDC sign-in left in its pending-link cookie. */
+export function pendingLink(c: AuthClient): Promise<ApiResult<PendingLinkResponse>> {
+  return c.oidcPending();
+}
+
+/** Links the pending IdP identity to the signed-in user and returns the updated user. */
+export function completePendingLink(c: AuthClient): Promise<ApiResult<MeResponse>> {
+  return c.oidcLinkPending();
+}

package/src/password-credential.ts

@@ -0,0 +1,30 @@
+// Chromium-only and absent from TypeScript's DOM lib; its instances are plain Credentials,
+// which navigator.credentials.store accepts.
+// https://w3c.github.io/webappsec-credential-management/#passwordcredential
+type PasswordCredentialCtor = new (data: { id: string; password: string }) => Credential;
+
+/**
+ * Asks the browser's password manager to save username and password after a form that
+ * submits over fetch, where no navigation follows for its own save heuristic to see. Does
+ * nothing where PasswordCredential is missing, for an empty username or password, and when
+ * the browser declines; never rejects.
+ */
+export async function storePasswordCredential(username: string, password: string): Promise<void> {
+  if (username === "" || password === "") {
+    return;
+  }
+  const g = globalThis as {
+    readonly PasswordCredential?: PasswordCredentialCtor;
+    readonly navigator?: { readonly credentials?: CredentialsContainer };
+  };
+  const ctor = g.PasswordCredential;
+  const store = g.navigator?.credentials;
+  if (typeof ctor !== "function" || store === undefined) {
+    return;
+  }
+  try {
+    await store.store(new ctor({ id: username, password }));
+  } catch {
+    // A declined, blocked or unimplemented store is not the caller's failure.
+  }
+}

package/src/secret.ts

@@ -0,0 +1,42 @@
+import { signal } from "@cplieger/reactive/signal";
+import type { ReadonlySignal } from "@cplieger/reactive/signal";
+
+/** A secret shown to the user once, such as a new API key or a recovery link. */
+export interface ShownOnce {
+  /** The plaintext until it is cleared, then null for good. */
+  readonly value: ReadonlySignal<string | null>;
+  /** Clears the value now; later calls do nothing. */
+  dismiss(): void;
+}
+
+/**
+ * Holds plaintext for display and clears it on dismiss, on the page's pagehide (so a page
+ * restored from the back-forward cache shows nothing), and after clearAfterMs when given.
+ * Throws unless clearAfterMs, when given, is a finite number greater than 0.
+ */
+export function shownOnce(plaintext: string, o?: { readonly clearAfterMs?: number }): ShownOnce {
+  const after = o?.clearAfterMs;
+  if (after !== undefined && !(Number.isFinite(after) && after > 0)) {
+    throw new RangeError(`shownOnce: clearAfterMs must be a finite number above 0, got ${after}`);
+  }
+  const value = signal<string | null>(plaintext);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const dismiss = (): void => {
+    clearTimeout(timer);
+    globalThis.removeEventListener("pagehide", dismiss);
+    value.value = null;
+  };
+  globalThis.addEventListener("pagehide", dismiss);
+  if (after !== undefined) {
+    timer = setTimeout(dismiss, after);
+  }
+  return {
+    value: {
+      get value() {
+        return value.value;
+      },
+      peek: () => value.peek(),
+    },
+    dismiss,
+  };
+}

package/src/sessions.ts

@@ -0,0 +1,63 @@
+import type { ApiResult } from "@cplieger/reactive/fetch";
+import { signal } from "@cplieger/reactive/signal";
+import type { ReadonlySignal } from "@cplieger/reactive/signal";
+import type { AuthClient } from "./client.js";
+import type { SessionView } from "./wire.js";
+
+/** The signed-in user's device list and the calls that change it. */
+export interface SessionsModel {
+  /** Empty until the first successful refresh. */
+  readonly sessions: ReadonlySignal<readonly SessionView[]>;
+  /** Replaces the list with the server's; a refusal leaves the list as it was. */
+  refresh(): Promise<ApiResult<void>>;
+  revoke(id: string): Promise<ApiResult<void>>;
+  revokeOthers(): Promise<ApiResult<void>>;
+  /** An empty label clears the session's label. */
+  rename(id: string, label: string): Promise<ApiResult<void>>;
+}
+
+/**
+ * A device-list model over c. Each change applies to the list only after the server accepts
+ * it, by the rule the server applied, so the list needs no refresh after a change.
+ */
+export function createSessionsModel(c: AuthClient): SessionsModel {
+  const list = signal<readonly SessionView[]>([]);
+  const after = async (
+    call: Promise<ApiResult<void>>,
+    apply: (s: readonly SessionView[]) => readonly SessionView[],
+  ): Promise<ApiResult<void>> => {
+    const res = await call;
+    if (res.ok) {
+      list.value = apply(list.peek());
+    }
+    return res;
+  };
+  return {
+    sessions: {
+      get value() {
+        return list.value;
+      },
+      peek: () => list.peek(),
+    },
+    refresh: async () => {
+      const res = await c.sessions();
+      if (!res.ok) {
+        return res;
+      }
+      list.value = res.data;
+      return { ...res, data: undefined };
+    },
+    revoke: (id) => after(c.revokeSession(id), (s) => s.filter((x) => x.id !== id)),
+    revokeOthers: () => after(c.revokeOtherSessions(), (s) => s.filter((x) => x.current)),
+    rename: (id, label) =>
+      after(c.renameSession(id, { name: label }), (s) =>
+        s.map((x) => {
+          if (x.id !== id) {
+            return x;
+          }
+          const { label: _old, ...rest } = x;
+          return label === "" ? rest : { ...rest, label };
+        }),
+      ),
+  };
+}

package/src/stepup.ts

@@ -0,0 +1,112 @@
+import type { ApiErr, ApiResult } from "@cplieger/reactive/fetch";
+import type { AuthClient } from "./client.js";
+import { assign } from "./navigate.js";
+import { startOIDC } from "./oidc.js";
+import { stepUpWithPasskey } from "./webauthn.js";
+import type { StepUpOutcome } from "./webauthn.js";
+import { authCode, errorReason } from "./wire.js";
+import type { MeResponse } from "./wire.js";
+
+/** Asks the user how to re-authenticate, given the methods the account holds. */
+export type StepUpPrompt = (
+  methods: MeResponse["methods"],
+) => Promise<"password" | "passkey" | "oidc" | "cancel">;
+
+export interface StepUpOptions {
+  readonly prompt: StepUpPrompt;
+  /** The user's current password, or null when the user cancels. */
+  readonly password: () => Promise<string | null>;
+  /**
+   * Where an OIDC step-up returns: the app's own relative path, at most 512 bytes, in which
+   * the app encodes what to continue. Default location.pathname + location.search, or
+   * location.pathname, or "/", the first that fits 512 bytes counted in UTF-8.
+   */
+  readonly redirect?: string;
+  /** Default location.assign. */
+  readonly navigate?: (url: string) => void;
+}
+
+export type StepUpResult<T> =
+  /** The action's own result, after at most one retry. */
+  | { readonly kind: "done"; readonly result: ApiResult<T> }
+  | { readonly kind: "cancelled" }
+  | {
+      readonly kind: "step-up-failed";
+      readonly error: ApiErr | Exclude<StepUpOutcome, { kind: "stepped-up" }>;
+    }
+  /** OIDC: the page is leaving; nothing was retried. */
+  | { readonly kind: "redirecting" };
+
+const MAX_REDIRECT_BYTES = 512;
+
+function fits(path: string): boolean {
+  return new TextEncoder().encode(path).length <= MAX_REDIRECT_BYTES;
+}
+
+function defaultRedirect(): string {
+  const { pathname, search } = globalThis.location;
+  if (fits(pathname + search)) {
+    return pathname + search;
+  }
+  return fits(pathname) ? pathname : "/";
+}
+
+/**
+ * Runs action; on an auth_recent_auth_required refusal with no reason, asks prompt for a
+ * method, re-authenticates and retries action once. A refusal with a reason (such as
+ * reenable_needs_other_method) is one a step-up cannot cure, so it is returned as done. The
+ * OIDC branch navigates away and never re-runs action: the app continues from its own
+ * redirect. Keeps nothing in browser storage and sends no request of its own beyond the
+ * client's me and step-up routes.
+ */
+export async function withStepUp<T>(
+  c: AuthClient,
+  action: () => Promise<ApiResult<T>>,
+  o: StepUpOptions,
+): Promise<StepUpResult<T>> {
+  const first = await action();
+  if (
+    first.ok ||
+    authCode(first) !== "auth_recent_auth_required" ||
+    errorReason(first) !== undefined
+  ) {
+    return { kind: "done", result: first };
+  }
+  const me = await c.me();
+  if (!me.ok) {
+    return { kind: "step-up-failed", error: me };
+  }
+  const retry = async (): Promise<StepUpResult<T>> => ({ kind: "done", result: await action() });
+  const choice = await o.prompt(me.data.methods);
+  switch (choice) {
+    case "cancel":
+      return { kind: "cancelled" };
+    case "password": {
+      const password = await o.password();
+      if (password === null) {
+        return { kind: "cancelled" };
+      }
+      const res = await c.stepUpPassword({ password });
+      return res.ok ? retry() : { kind: "step-up-failed", error: res };
+    }
+    case "passkey": {
+      const out = await stepUpWithPasskey(c);
+      switch (out.kind) {
+        case "stepped-up":
+          return retry();
+        case "cancelled":
+          return { kind: "cancelled" };
+        default:
+          return { kind: "step-up-failed", error: out };
+      }
+    }
+    case "oidc": {
+      const res = await startOIDC(c, "stepup", o.redirect ?? defaultRedirect());
+      if (!res.ok) {
+        return { kind: "step-up-failed", error: res };
+      }
+      (o.navigate ?? assign)(res.data.url);
+      return { kind: "redirecting" };
+    }
+  }
+}