@stapel/auth-react 1.0.0

package/src/api/authApi.ts

@@ -0,0 +1,332 @@
+import type { StapelClient, StapelRequestOptions } from "@stapel/core";
+import type {
+  AuthResponse,
+  AuditPage,
+  AuthSession,
+  Capabilities,
+  ChangeOldVerifiedResponse,
+  DelayedChangeInitiatedResponse,
+  DelayedChangeStatus,
+  LoginResponse,
+  OtpChannel,
+  OtpRequestResponse,
+  Passkey,
+  PasskeyAuthenticateBeginResponse,
+  PasskeyRegisterBeginResponse,
+  PasswordMethods,
+  QrGenerateResponse,
+  QrStatusResponse,
+  QrType,
+  RefreshResponse,
+  SecurityStatus,
+  SsoLookupResponse,
+  StapelUser,
+  StatusResponse,
+  TotpDisableRequest,
+  TotpSetupConfirmResponse,
+  TotpSetupResponse,
+  VerificationCompleteResponse,
+  VerificationEnvelope,
+  VerificationFactorId,
+  VerificationInitiateResponse,
+} from "./types.js";
+
+/**
+ * CSRF rule for cookie-authenticated browser clients (auth-sa.md §"CSRF"):
+ * the simplest SPA rule is to always send `X-Requested-With: XMLHttpRequest`
+ * on mutating requests. Header-token clients are exempt but it is harmless
+ * for them, so we send it on every mutation.
+ */
+const CSRF_HEADERS: Record<string, string> = {
+  "X-Requested-With": "XMLHttpRequest",
+};
+
+function mutating(
+  options?: Omit<StapelRequestOptions, "method" | "body">
+): Omit<StapelRequestOptions, "method" | "body"> {
+  return {
+    ...options,
+    headers: { ...CSRF_HEADERS, ...options?.headers },
+  };
+}
+
+/**
+ * The typed auth surface. One method per auth-sa.md endpoint that a JS client
+ * may call. Browser-redirect endpoints (OAuth authorize, SSO login, QR scan,
+ * magic-link verify) are intentionally absent — see `authUrls`.
+ */
+export interface AuthApi {
+  readonly client: StapelClient;
+
+  // Capabilities & identity
+  capabilities(): Promise<Capabilities>;
+  me(): Promise<StapelUser>;
+  logout(): Promise<StatusResponse>;
+
+  // Email / Phone OTP (auth-sa.md §1–2)
+  otpRequest(channel: OtpChannel, value: string, captchaToken?: string): Promise<OtpRequestResponse>;
+  otpVerify(channel: OtpChannel, value: string, code: string): Promise<AuthResponse>;
+
+  // Password (auth-sa.md §3–5)
+  passwordLogin(login: string, password: string): Promise<LoginResponse>;
+  passwordMethods(): Promise<PasswordMethods>;
+  passwordChange(oldPassword: string, newPassword: string): Promise<StatusResponse>;
+  passwordChangeOtpRequest(method: OtpChannel): Promise<OtpRequestResponse>;
+  passwordChangeOtpVerify(method: OtpChannel, code: string, newPassword: string): Promise<StatusResponse>;
+  passwordResetRequest(channel: OtpChannel, value: string): Promise<OtpRequestResponse>;
+  passwordResetVerify(channel: OtpChannel, value: string, code: string, newPassword: string): Promise<AuthResponse>;
+
+  // Anonymous (auth-sa.md §6)
+  anonymous(deviceId?: string): Promise<AuthResponse>;
+
+  // OAuth (auth-sa.md §7, option B)
+  oauthLogin(provider: string, accessToken: string): Promise<LoginResponse>;
+
+  // TOTP (auth-sa.md §11)
+  totpChallengeVerify(challengeToken: string, proof: { code?: string; backup_code?: string }): Promise<AuthResponse>;
+  totpSetup(): Promise<TotpSetupResponse>;
+  totpSetupConfirm(code: string): Promise<TotpSetupConfirmResponse>;
+  totpDisable(request: TotpDisableRequest): Promise<StatusResponse>;
+  totpDisableOtpRequest(): Promise<OtpRequestResponse>;
+
+  // Verification / step-up factor flow (auth-sa.md §11)
+  verificationGet(challengeId: string): Promise<VerificationEnvelope>;
+  verificationInitiate(challengeId: string, factor: VerificationFactorId): Promise<VerificationInitiateResponse>;
+  verificationComplete(challengeId: string, body: Record<string, unknown>): Promise<VerificationCompleteResponse>;
+
+  // Security status (auth-sa.md §10)
+  securityStatus(): Promise<SecurityStatus>;
+
+  // Sessions (auth-sa.md §12)
+  sessions(): Promise<readonly AuthSession[]>;
+  confirmSession(id: string): Promise<StatusResponse>;
+  revokeSession(id: string): Promise<StatusResponse>;
+  revokeOtherSessions(): Promise<StatusResponse>;
+
+  // Token refresh (auth-sa.md §13)
+  tokenRefresh(refresh?: string): Promise<RefreshResponse>;
+
+  // QR (auth-sa.md §8)
+  qrGenerate(type: QrType, redirectUrl: string, allowUnauthenticatedScanner?: boolean): Promise<QrGenerateResponse>;
+  qrStatus(key: string): Promise<QrStatusResponse>;
+  qrConfirm(key: string): Promise<StatusResponse>;
+  qrReject(key: string): Promise<StatusResponse>;
+
+  // Magic links (auth-sa.md §15)
+  magicRequest(email: string, redirectUrl?: string): Promise<StatusResponse>;
+
+  // Passkeys (auth-sa.md §17)
+  passkeys(): Promise<readonly Passkey[]>;
+  passkeyRegisterBegin(): Promise<PasskeyRegisterBeginResponse>;
+  passkeyRegisterComplete(credential: unknown, deviceName?: string): Promise<Passkey>;
+  passkeyAuthenticateBegin(email?: string): Promise<PasskeyAuthenticateBeginResponse>;
+  passkeyAuthenticateComplete(sessionKey: string, credential: unknown): Promise<AuthResponse>;
+  passkeyRemove(id: string): Promise<void>;
+
+  // Authenticator change (auth-sa.md §9)
+  changeInstantRequestOld(channel: OtpChannel): Promise<OtpRequestResponse>;
+  changeInstantVerifyOld(channel: OtpChannel, code: string): Promise<ChangeOldVerifiedResponse>;
+  changeInstantRequestNew(channel: OtpChannel, value: string, changeToken: string): Promise<OtpRequestResponse>;
+  changeInstantVerifyNew(channel: OtpChannel, value: string, code: string, changeToken: string): Promise<AuthResponse>;
+  changeDelayedInitiate(channel: OtpChannel, value: string): Promise<DelayedChangeInitiatedResponse>;
+  changeDelayedStatus(channel: OtpChannel): Promise<DelayedChangeStatus>;
+  changeDelayedCancel(channel: OtpChannel, changeRequestId: string): Promise<StatusResponse>;
+
+  // SSO (auth-sa.md §18)
+  ssoLookup(domain: string): Promise<SsoLookupResponse>;
+
+  // Audit log (auth-sa.md §16)
+  auditLog(page?: number): Promise<AuditPage>;
+}
+
+/**
+ * Build the auth API bound to an injected {@link StapelClient} (per-module
+ * override from `StapelProvider`, the fork-resolution seam of §7.2). All
+ * mutations carry the CSRF header.
+ */
+export function createAuthApi(client: StapelClient): AuthApi {
+  return {
+    client,
+
+    capabilities: () => client.get("/capabilities/"),
+    me: () => client.get("/me/"),
+    logout: () => client.post("/logout/", undefined, mutating()),
+
+    otpRequest: (channel, value, captchaToken) =>
+      client.post(
+        `/${channel}/request/`,
+        captchaToken === undefined
+          ? { [channel]: value }
+          : { [channel]: value, captcha_token: captchaToken },
+        mutating()
+      ),
+    otpVerify: (channel, value, code) =>
+      client.post(`/${channel}/verify/`, { [channel]: value, code }, mutating()),
+
+    passwordLogin: (login, password) =>
+      client.post("/password/login/", { login, password }, mutating()),
+    passwordMethods: () => client.get("/password/methods/"),
+    passwordChange: (oldPassword, newPassword) =>
+      client.post(
+        "/password/change/",
+        { old_password: oldPassword, new_password: newPassword },
+        mutating()
+      ),
+    passwordChangeOtpRequest: (method) =>
+      client.post("/password/change/otp/request/", { method }, mutating()),
+    passwordChangeOtpVerify: (method, code, newPassword) =>
+      client.post(
+        "/password/change/otp/verify/",
+        { method, code, new_password: newPassword },
+        mutating()
+      ),
+    passwordResetRequest: (channel, value) =>
+      client.post(
+        `/password/reset/${channel}/request/`,
+        { [channel]: value },
+        mutating()
+      ),
+    passwordResetVerify: (channel, value, code, newPassword) =>
+      client.post(
+        `/password/reset/${channel}/verify/`,
+        { [channel]: value, code, new_password: newPassword },
+        mutating()
+      ),
+
+    anonymous: (deviceId) =>
+      client.post(
+        "/anonymous/",
+        deviceId === undefined ? {} : { device_id: deviceId },
+        mutating()
+      ),
+
+    oauthLogin: (provider, accessToken) =>
+      client.post(
+        "/oauth/login/",
+        { provider, access_token: accessToken },
+        mutating()
+      ),
+
+    totpChallengeVerify: (challengeToken, proof) =>
+      client.post(
+        "/totp/challenge/verify/",
+        { challenge_token: challengeToken, ...proof },
+        mutating()
+      ),
+    totpSetup: () => client.post("/totp/setup/", undefined, mutating()),
+    totpSetupConfirm: (code) =>
+      client.post("/totp/setup/confirm/", { code }, mutating()),
+    totpDisable: (request) => client.post("/totp/disable/", request, mutating()),
+    totpDisableOtpRequest: () =>
+      client.post("/totp/disable-otp/request/", undefined, mutating()),
+
+    verificationGet: (challengeId) =>
+      client.get(`/verification/${challengeId}/`),
+    verificationInitiate: (challengeId, factor) =>
+      client.post(`/verification/${challengeId}/initiate/`, { factor }, mutating()),
+    verificationComplete: (challengeId, body) =>
+      client.post(`/verification/${challengeId}/complete/`, body, mutating()),
+
+    securityStatus: () => client.get("/security/status/"),
+
+    sessions: () => client.get("/sessions/"),
+    confirmSession: (id) =>
+      client.post(`/sessions/${id}/confirm/`, undefined, mutating()),
+    revokeSession: (id) => client.delete(`/sessions/${id}/`, mutating()),
+    revokeOtherSessions: () => client.delete("/sessions/", mutating()),
+
+    tokenRefresh: (refresh) =>
+      refresh === undefined
+        ? client.get("/token/refresh/")
+        : client.post("/token/refresh/", { refresh }, mutating()),
+
+    qrGenerate: (type, redirectUrl, allowUnauthenticatedScanner) =>
+      client.post(
+        "/qr/generate/",
+        allowUnauthenticatedScanner === undefined
+          ? { type, redirect_url: redirectUrl }
+          : {
+              type,
+              redirect_url: redirectUrl,
+              allow_unauthenticated_scanner: allowUnauthenticatedScanner,
+            },
+        mutating()
+      ),
+    qrStatus: (key) => client.get(`/qr/${key}/status/`),
+    qrConfirm: (key) => client.post(`/qr/${key}/confirm/`, undefined, mutating()),
+    qrReject: (key) => client.post(`/qr/${key}/reject/`, undefined, mutating()),
+
+    magicRequest: (email, redirectUrl) =>
+      client.post(
+        "/magic/request/",
+        redirectUrl === undefined ? { email } : { email, redirect_url: redirectUrl },
+        mutating()
+      ),
+
+    passkeys: () =>
+      client
+        .get<{ passkeys: readonly Passkey[] }>("/passkey/")
+        .then((r) => r.passkeys),
+    passkeyRegisterBegin: () =>
+      client.post("/passkey/register/begin/", undefined, mutating()),
+    passkeyRegisterComplete: (credential, deviceName) =>
+      client.post(
+        "/passkey/register/complete/",
+        deviceName === undefined
+          ? { credential }
+          : { credential, device_name: deviceName },
+        mutating()
+      ),
+    passkeyAuthenticateBegin: (email) =>
+      client.post(
+        "/passkey/authenticate/begin/",
+        email === undefined ? {} : { email },
+        mutating()
+      ),
+    passkeyAuthenticateComplete: (sessionKey, credential) =>
+      client.post(
+        "/passkey/authenticate/complete/",
+        { session_key: sessionKey, credential },
+        mutating()
+      ),
+    passkeyRemove: (id) => client.delete(`/passkey/${id}/`, mutating()),
+
+    changeInstantRequestOld: (channel) =>
+      client.post(`/${channel}/change/instant/request-old/`, undefined, mutating()),
+    changeInstantVerifyOld: (channel, code) =>
+      client.post(`/${channel}/change/instant/verify-old/`, { code }, mutating()),
+    changeInstantRequestNew: (channel, value, changeToken) =>
+      client.post(
+        `/${channel}/change/instant/request-new/`,
+        { [channel]: value, change_token: changeToken },
+        mutating()
+      ),
+    changeInstantVerifyNew: (channel, value, code, changeToken) =>
+      client.post(
+        `/${channel}/change/instant/verify-new/`,
+        { [channel]: value, code, change_token: changeToken },
+        mutating()
+      ),
+    changeDelayedInitiate: (channel, value) =>
+      client.post(
+        `/${channel}/change/delayed/initiate/`,
+        { [channel]: value },
+        mutating()
+      ),
+    changeDelayedStatus: (channel) =>
+      client.get(`/${channel}/change/delayed/status/`),
+    changeDelayedCancel: (channel, changeRequestId) =>
+      client.post(
+        `/${channel}/change/delayed/cancel/`,
+        { change_request_id: changeRequestId },
+        mutating()
+      ),
+
+    ssoLookup: (domain) => client.get("/sso/lookup/", { query: { domain } }),
+
+    auditLog: (page) =>
+      client.get("/security/audit/", {
+        query: page === undefined ? {} : { page },
+      }),
+  };
+}

package/src/api/types.ts

@@ -0,0 +1,291 @@
+/**
+ * Wire types for the stapel-auth HTTP contract (auth-sa.md §1–18).
+ *
+ * These are hand-authored here because the auth backend does not yet publish
+ * an `openapi.json` artifact to this monorepo. When it does, this file is the
+ * codegen target (frontend-standard §2/§3): the shapes below are transcribed
+ * verbatim from auth-sa.md's documented request/response bodies so a future
+ * `regen` produces a compatible surface.
+ */
+
+/** Result status of any flow that ends in a session (auth-sa.md §"AuthResponse"). */
+export type AuthStatus = "LOGGED_IN" | "REGISTERED" | "MERGED" | "MODIFIED";
+
+/** The authenticated principal. Backend adds fields freely; kept open. */
+export interface StapelUser {
+  readonly id: string;
+  readonly username?: string;
+  readonly email?: string | null;
+  readonly phone?: string | null;
+  readonly is_anonymous?: boolean;
+  readonly [extra: string]: unknown;
+}
+
+/** Access/refresh JWT pair returned in the body (also set as cookies). */
+export interface AuthTokens {
+  readonly access: string;
+  readonly refresh: string;
+}
+
+/** Returned by every flow that results in a session. */
+export interface AuthResponse {
+  readonly status: AuthStatus;
+  readonly user: StapelUser;
+  readonly tokens: AuthTokens;
+}
+
+/** Returned instead of `AuthResponse` when the account has TOTP enabled. */
+export interface TOTPChallengeResponse {
+  readonly status: "TOTP_REQUIRED";
+  readonly challenge_token: string;
+  readonly expires_in: number;
+}
+
+/**
+ * The `oneOf` login union (discriminator: `status`). Narrow with
+ * `if (r.status === "TOTP_REQUIRED")`.
+ */
+export type LoginResponse = AuthResponse | TOTPChallengeResponse;
+
+/** Narrowing helper for the login union. */
+export function isTotpChallenge(r: LoginResponse): r is TOTPChallengeResponse {
+  return r.status === "TOTP_REQUIRED";
+}
+
+/** `{ message, target }` — target is the masked destination to display. */
+export interface OtpRequestResponse {
+  readonly message: string;
+  readonly target: string;
+}
+
+/** Simple status envelopes returned by several mutations. */
+export interface StatusResponse {
+  readonly status: string;
+}
+
+// ── Capabilities (auth-sa.md §"Which login methods to render") ──────────────
+
+export interface OAuthProviderInfo {
+  readonly id: string;
+  readonly name: string;
+}
+
+export interface RegistrationCapabilities {
+  readonly phone: boolean;
+  readonly email: boolean;
+  readonly password: boolean;
+  readonly oauth: readonly OAuthProviderInfo[];
+  readonly sso: boolean;
+  readonly anonymous: boolean;
+}
+
+export interface LoginCapabilities {
+  readonly phone: boolean;
+  readonly email: boolean;
+  readonly password: boolean;
+  readonly oauth: readonly OAuthProviderInfo[];
+  readonly sso: boolean;
+  readonly qr: boolean;
+  readonly passkey: boolean;
+  readonly magic_link: boolean;
+}
+
+export interface Capabilities {
+  readonly registration: RegistrationCapabilities;
+  readonly login: LoginCapabilities;
+}
+
+// ── Password change methods (auth-sa.md §4) ─────────────────────────────────
+
+export type PasswordChangeMethod = "password" | "email" | "phone";
+
+export interface PasswordMethodEntry {
+  readonly method: PasswordChangeMethod;
+  readonly target?: string;
+}
+
+export interface PasswordMethods {
+  readonly has_password: boolean;
+  readonly methods: readonly PasswordMethodEntry[];
+}
+
+// ── Security status (auth-sa.md §10) ────────────────────────────────────────
+
+export interface SecurityStatus {
+  readonly password: { readonly is_set: boolean };
+  readonly totp: {
+    readonly is_enabled: boolean;
+    readonly backup_codes_remaining: number;
+  };
+  readonly email: { readonly value: string | null; readonly is_verified: boolean };
+  readonly phone: { readonly value: string | null; readonly is_verified: boolean };
+  readonly oauth: { readonly connected_providers: readonly string[] };
+  readonly sessions: { readonly active_count: number };
+  readonly passkeys: { readonly count: number };
+}
+
+// ── Sessions (auth-sa.md §12) ───────────────────────────────────────────────
+
+export type SessionDeviceType =
+  | "phone"
+  | "tablet"
+  | "desktop"
+  | "api"
+  | "unknown";
+
+export interface AuthSession {
+  readonly id: string;
+  readonly device_type: SessionDeviceType;
+  readonly device_name: string;
+  readonly device_details: string;
+  readonly ip_address: string;
+  readonly created_at: string;
+  readonly last_used_at: string;
+  readonly is_current: boolean;
+  readonly is_suspicious: boolean;
+}
+
+// ── TOTP (auth-sa.md §11) ───────────────────────────────────────────────────
+
+export interface TotpSetupResponse {
+  readonly secret: string;
+  readonly qr_uri: string;
+  readonly expires_in: number;
+}
+
+export interface TotpSetupConfirmResponse {
+  readonly backup_codes: readonly string[];
+}
+
+/** `oneOf` discriminated by `method` (auth-sa.md §"Disable TOTP"). */
+export type TotpDisableRequest =
+  | { readonly method: "totp"; readonly code: string }
+  | { readonly method: "backup"; readonly backup_code: string }
+  | { readonly method: "otp"; readonly otp_code: string };
+
+// ── Verification / step-up (auth-sa.md §11 "verification challenges") ────────
+
+export type VerificationFactorId =
+  | "otp_email"
+  | "otp_phone"
+  | "totp"
+  | "passkey";
+
+/** The `verification` object inside the 403 envelope. */
+export interface VerificationEnvelope {
+  readonly challenge_id: string;
+  readonly scope: string;
+  readonly factors: readonly VerificationFactorId[];
+  readonly expires_at: number;
+}
+
+export interface VerificationInitiateResponse {
+  readonly factor: VerificationFactorId;
+  /** For otp_* — `{ target }`; for passkey — `{ session_key, options }`. */
+  readonly data: Record<string, unknown>;
+}
+
+export interface VerificationCompleteResponse {
+  readonly verified: boolean;
+  readonly verification_token: string;
+}
+
+// ── QR (auth-sa.md §8) ──────────────────────────────────────────────────────
+
+export type QrType = "session_share" | "login_request";
+
+export interface QrGenerateResponse {
+  readonly key: string;
+  readonly type: QrType;
+  readonly expires_in: number;
+  readonly scan_url: string;
+}
+
+export type QrStatusValue = "pending" | "fulfilled" | "expired" | "rejected";
+
+export interface QrStatusResponse {
+  readonly status: QrStatusValue;
+  /** Present only on `login_request` fulfilment. */
+  readonly access_token?: string;
+  readonly refresh_token?: string;
+}
+
+// ── Passkeys (auth-sa.md §17) ───────────────────────────────────────────────
+
+export interface Passkey {
+  readonly id: string;
+  readonly device_name: string;
+  readonly aaguid: string;
+  readonly transports: readonly string[];
+  readonly created_at: string;
+  readonly last_used_at: string | null;
+}
+
+export interface PasskeyRegisterBeginResponse {
+  /** PublicKeyCredentialCreationOptions (JSON form). */
+  readonly options: Record<string, unknown>;
+}
+
+export interface PasskeyAuthenticateBeginResponse {
+  readonly session_key: string;
+  /** PublicKeyCredentialRequestOptions (JSON form). */
+  readonly options: Record<string, unknown>;
+}
+
+// ── Authenticator change (auth-sa.md §9) ────────────────────────────────────
+
+export interface ChangeOldVerifiedResponse {
+  readonly status: "OLD_VERIFIED";
+  readonly change_token: string;
+  readonly expires_at: string;
+}
+
+export interface DelayedChangeInitiatedResponse {
+  readonly status: "PENDING";
+  readonly change_request_id: string;
+  readonly scheduled_at: string;
+  readonly can_cancel_until: string;
+}
+
+export type DelayedChangeStatus =
+  | { readonly has_pending_change: false }
+  | {
+      readonly has_pending_change?: true;
+      readonly change_request_id: string;
+      readonly scheduled_at: string;
+      readonly can_cancel_until: string;
+    };
+
+// ── SSO (auth-sa.md §18) ────────────────────────────────────────────────────
+
+export interface SsoLookupResponse {
+  readonly sso_required: boolean;
+  readonly org_slug: string | null;
+  readonly protocol?: "saml" | "oidc";
+}
+
+// ── Audit log (auth-sa.md §16) ──────────────────────────────────────────────
+
+export interface AuditEvent {
+  readonly id: string;
+  readonly event_type: string;
+  readonly ip_address: string;
+  readonly user_agent: string;
+  readonly metadata: Record<string, unknown>;
+  readonly created_at: string;
+}
+
+export interface AuditPage {
+  readonly results: readonly AuditEvent[];
+  readonly count: number;
+  readonly next: number | null;
+}
+
+/** `{ access, refresh }` from POST/GET /token/refresh/. */
+export interface RefreshResponse {
+  readonly access: string;
+  readonly refresh: string;
+}
+
+/** Which identifier channel an OTP flow uses. */
+export type OtpChannel = "email" | "phone";