@owlmeans/web-oauth 0.1.18-rc.1

package/src/@/components/ui/button.tsx

@@ -0,0 +1,60 @@
+// shadcn button — sourced from shadcn (new-york) 2026-05-23
+import * as React from 'react'
+import { Slot } from '@radix-ui/react-slot'
+import { cva, type VariantProps } from 'class-variance-authority'
+
+import { cn } from '../../lib/utils.js'
+
+const buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive cursor-pointer",
+  {
+    variants: {
+      variant: {
+        default:
+          "bg-primary text-primary-foreground shadow-xs hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-white shadow-xs hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60",
+        outline:
+          "border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50",
+        secondary:
+          "bg-secondary text-secondary-foreground shadow-xs hover:bg-secondary/80",
+        ghost:
+          "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-9 px-4 py-2 has-[>svg]:px-3",
+        sm: "h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5",
+        lg: "h-10 rounded-md px-6 has-[>svg]:px-4",
+        icon: "size-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+function Button({
+  className,
+  variant,
+  size,
+  asChild = false,
+  ...props
+}: React.ComponentProps<"button"> &
+  VariantProps<typeof buttonVariants> & {
+    asChild?: boolean
+  }) {
+  const Comp = asChild ? Slot : "button"
+
+  return (
+    <Comp
+      data-slot="button"
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  )
+}
+
+export { Button, buttonVariants }

package/src/@/components/ui/card.tsx

@@ -0,0 +1,93 @@
+// shadcn card — sourced from shadcn (new-york) 2026-05-23
+import * as React from 'react'
+
+import { cn } from '../../lib/utils.js'
+
+function Card({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card"
+      className={cn(
+        "bg-card text-card-foreground flex flex-col gap-6 rounded-xl border py-6 shadow-sm",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        "@container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-1.5 px-6 has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn("leading-none font-semibold", className)}
+      {...props}
+    />
+  )
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-muted-foreground text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+function CardAction({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn(
+        "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("px-6", className)}
+      {...props}
+    />
+  )
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn("flex items-center px-6 [.border-t]:pt-6", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardAction,
+  CardDescription,
+  CardContent,
+}

package/src/@/components/ui/input.tsx

@@ -0,0 +1,22 @@
+// shadcn input — sourced from shadcn (new-york) 2026-05-23
+import * as React from 'react'
+
+import { cn } from '../../lib/utils.js'
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        "file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground dark:bg-input/30 border-input flex h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]",
+        "aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Input }

package/src/@/components/ui/label.tsx

@@ -0,0 +1,23 @@
+// shadcn label — sourced from shadcn (new-york) 2026-05-23
+import * as React from 'react'
+import * as LabelPrimitive from '@radix-ui/react-label'
+
+import { cn } from '../../lib/utils.js'
+
+function Label({
+  className,
+  ...props
+}: React.ComponentProps<typeof LabelPrimitive.Root>) {
+  return (
+    <LabelPrimitive.Root
+      data-slot="label"
+      className={cn(
+        "flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Label }

package/src/@/globals.css

@@ -0,0 +1,57 @@
+@import "tailwindcss";
+
+@source "../..";
+
+@theme {
+  --color-background:           oklch(1 0 0);
+  --color-foreground:           oklch(0.145 0 0);
+
+  --color-card:                 oklch(1 0 0);
+  --color-card-foreground:      oklch(0.145 0 0);
+
+  --color-popover:              oklch(1 0 0);
+  --color-popover-foreground:   oklch(0.145 0 0);
+
+  --color-primary:              oklch(0.205 0 0);
+  --color-primary-foreground:   oklch(0.985 0 0);
+
+  --color-secondary:            oklch(0.97 0 0);
+  --color-secondary-foreground: oklch(0.205 0 0);
+
+  --color-muted:                oklch(0.97 0 0);
+  --color-muted-foreground:     oklch(0.556 0 0);
+
+  --color-accent:               oklch(0.97 0 0);
+  --color-accent-foreground:    oklch(0.205 0 0);
+
+  --color-destructive:          oklch(0.577 0.245 27.325);
+  --color-success:              oklch(0.62 0.18 145);
+
+  --color-border:               oklch(0.922 0 0);
+  --color-input:                oklch(0.922 0 0);
+  --color-ring:                 oklch(0.708 0 0);
+
+  --radius:                     0.625rem;
+}
+
+.dark {
+  --color-background:           oklch(0.145 0 0);
+  --color-foreground:           oklch(0.985 0 0);
+  --color-card:                 oklch(0.205 0 0);
+  --color-card-foreground:      oklch(0.985 0 0);
+  --color-popover:              oklch(0.205 0 0);
+  --color-popover-foreground:   oklch(0.985 0 0);
+  --color-primary:              oklch(0.922 0 0);
+  --color-primary-foreground:   oklch(0.205 0 0);
+  --color-secondary:            oklch(0.269 0 0);
+  --color-secondary-foreground: oklch(0.985 0 0);
+  --color-muted:                oklch(0.269 0 0);
+  --color-muted-foreground:     oklch(0.708 0 0);
+  --color-accent:               oklch(0.269 0 0);
+  --color-accent-foreground:    oklch(0.985 0 0);
+  --color-destructive:          oklch(0.704 0.191 22.216);
+  --color-success:              oklch(0.7 0.18 145);
+  --color-border:               oklch(1 0 0 / 10%);
+  --color-input:                oklch(1 0 0 / 15%);
+  --color-ring:                 oklch(0.556 0 0);
+}

package/src/@/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/src/append.ts

@@ -0,0 +1,24 @@
+import { FLOW_STATE } from '@owlmeans/client-flow'
+import type { ClientContext } from '@owlmeans/client-context'
+import type { ClientConfig } from '@owlmeans/client-context'
+
+/**
+ * Fail fast when the one precondition these screens actually depend on is missing, rather than
+ * deep inside `suspendFlow` the first time somebody who is not signed in opens a consent screen.
+ *
+ * There is nothing else to register here: the three screens are bound through `oauthEntrypoints`
+ * (spread into the application's own entrypoint list, exactly like every other screen package in
+ * this framework), and the translations register themselves as a side effect of importing this
+ * package's barrel — `appendOAuthScreens` is the documented call an application makes, but the
+ * strings are already there whether it is called or not.
+ */
+export const appendOAuthScreens = <C extends ClientConfig, T extends ClientContext<C>>(context: T): T => {
+  if (!context.hasResource(FLOW_STATE)) {
+    throw new SyntaxError(
+      'web-oauth: no FLOW_STATE resource registered. Call appendFlowService (@owlmeans/web-flow) — '
+      + 'or whatever registers it in this app\'s makeContext — before appendOAuthScreens.'
+    )
+  }
+
+  return context
+}

package/src/components/consent-screen.tsx

@@ -0,0 +1,95 @@
+import { useContext } from '@owlmeans/client'
+import type { RoutedComponent } from '@owlmeans/client'
+import { useI18nLib } from '@owlmeans/client-i18n'
+import { OAUTH_I18N } from '../consts.js'
+import { useOAuthConsent } from '../hooks/use-oauth-consent.js'
+import { Button } from '../@/components/ui/button.js'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '../@/components/ui/card.js'
+
+/**
+ * The device/authorization-code consent screen. Full-page, no application chrome — the same
+ * shape `/dispatcher` and `/iam/interact/:uid` already render in, because a sign-in round trip is
+ * never a panel inside the application's own navigation.
+ *
+ * The screen refuses to render when framed: a device or code approval is exactly the click a
+ * clickjacking overlay would want to steal, and nothing about this decision needs to happen
+ * inside a frame.
+ */
+export const OAuthConsentScreen: RoutedComponent = () => {
+  const context = useContext()
+  const [query] = context.router().useSearchParams()
+  const ref = query.get('ref')
+  const t = useI18nLib(OAUTH_I18N, 'consent')
+  const { stage, view, errorKind, approve, deny, switchAccount } = useOAuthConsent(ref)
+
+  const framed = typeof window !== 'undefined' && window.top !== window.self
+
+  return (
+    <div style={{ minHeight: '100dvh', display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 16 }}>
+      <Card style={{ width: '100%', maxWidth: 440 }} data-testid="oauth-consent-card">
+        {framed ? (
+          <CardContent>
+            <p role="alert">{t('framed')}</p>
+          </CardContent>
+        ) : stage === 'checking' || stage === 'signing-in' ? (
+          <CardContent>
+            <p>{t('checking')}</p>
+          </CardContent>
+        ) : stage === 'loading' ? (
+          <CardContent>
+            <p>{t('loading')}</p>
+          </CardContent>
+        ) : stage === 'error' ? (
+          <CardContent>
+            <p role="alert" data-testid="oauth-consent-error">{t(errorKind == null || errorKind === 'failed' ? 'error' : `error-${errorKind}`)}</p>
+          </CardContent>
+        ) : view != null ? (
+          <>
+            <CardHeader>
+              <CardTitle data-testid="oauth-consent-client">{t('title', { client: view.client.name })}</CardTitle>
+              <CardDescription>
+                {view.client.origin === 'cimd' && view.client.host != null
+                  ? t('known-by-host', { host: view.client.host })
+                  : view.client.origin === 'dcr'
+                    ? t('unverified')
+                    : t('known')}
+              </CardDescription>
+            </CardHeader>
+            <CardContent style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+              {view.userCode != null && (
+                <p data-testid="oauth-consent-code">{t('device-code', { code: view.userCode })}</p>
+              )}
+              {view.deviceName != null && <p>{t('device-name', { name: view.deviceName })}</p>}
+              {view.redirectHost != null && <p>{t('redirect-host', { host: view.redirectHost })}</p>}
+              {view.localhostOnly === true && (
+                <p role="alert">{t('localhost-warning')}</p>
+              )}
+              <p>{t('scope', { scopes: view.scopes.join(', ') })}</p>
+              <div style={{ display: 'flex', gap: 8, justifyContent: 'flex-end' }}>
+                <Button
+                  type="button" variant="outline" disabled={stage === 'deciding'}
+                  data-testid="oauth-consent-deny" onClick={() => void deny()}
+                >
+                  {t('deny')}
+                </Button>
+                <Button
+                  type="button" disabled={stage === 'deciding'}
+                  data-testid="oauth-consent-approve" onClick={() => void approve()}
+                  autoFocus
+                >
+                  {t('approve')}
+                </Button>
+              </div>
+              <Button
+                type="button" variant="link" size="sm" disabled={stage === 'deciding'}
+                data-testid="oauth-consent-switch" onClick={() => void switchAccount()}
+              >
+                {t('switch-account')}
+              </Button>
+            </CardContent>
+          </>
+        ) : null}
+      </Card>
+    </div>
+  )
+}

package/src/components/device-screen.tsx

@@ -0,0 +1,81 @@
+import { useCallback, useEffect, useState } from 'react'
+import type { FormEvent } from 'react'
+import { useContext, useNavigate } from '@owlmeans/client'
+import type { RoutedComponent } from '@owlmeans/client'
+import { useI18nLib } from '@owlmeans/client-i18n'
+import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+import { makeFlowModel } from '@owlmeans/flow'
+import { normalizeUserCode, oauthFlow, OAuthFlowStep, OAUTH_PAYLOAD_REF } from '@owlmeans/oauth'
+import { OAUTH_I18N } from '../consts.js'
+import { Button } from '../@/components/ui/button.js'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '../@/components/ui/card.js'
+import { Input } from '../@/components/ui/input.js'
+import { Label } from '../@/components/ui/label.js'
+
+/**
+ * The device-verification screen (RFC 8628's `verification_uri`). Opened by the MCP, either bare
+ * (a person types the code they were shown) or complete (`?user_code=…`, already carrying it).
+ *
+ * Either way it goes through the SAME flow transition — `verify` → `next` → `consent` — so the
+ * two entry shapes converge onto one path before anything else runs.
+ */
+export const OAuthDeviceScreen: RoutedComponent = () => {
+  const context = useContext()
+  const nav = useNavigate()
+  const [query] = context.router().useSearchParams()
+  const t = useI18nLib(OAUTH_I18N, 'device')
+  const [code, setCode] = useState(query.get('user_code') ?? '')
+
+  const proceed = useCallback(async (typed: string) => {
+    const model = await makeFlowModel(oauthFlow)
+    model.enter(OAuthFlowStep.Verify)
+    model.updatePayload({ [OAUTH_PAYLOAD_REF]: normalizeUserCode(typed) })
+    model.transit('next', true)
+    const destination = model.step()
+    await nav.navigate(
+      context.entrypoint<ClientEntrypoint<string>>(destination.module!), { query: model.payload() }
+    )
+  }, [nav])
+
+  const initial = query.get('user_code')
+  const complete = initial != null && initial !== ''
+
+  useEffect(() => {
+    if (complete) void proceed(initial)
+  }, [complete, initial])
+
+  const onSubmit = (event: FormEvent) => {
+    event.preventDefault()
+    void proceed(code)
+  }
+
+  if (complete) {
+    return null
+  }
+
+  return (
+    <div style={{ minHeight: '100dvh', display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 16 }}>
+      <Card style={{ width: '100%', maxWidth: 380 }} data-testid="oauth-device-card">
+        <CardHeader>
+          <CardTitle>{t('title')}</CardTitle>
+          <CardDescription>{t('description')}</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <form onSubmit={onSubmit} style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
+              <Label htmlFor="oauth-device-code">{t('code-label')}</Label>
+              <Input
+                id="oauth-device-code" data-testid="oauth-device-input" autoComplete="off"
+                placeholder="XXXX-XXXX" value={code}
+                onChange={event => setCode(event.target.value)}
+              />
+            </div>
+            <Button type="submit" data-testid="oauth-device-submit" disabled={code.trim() === ''}>
+              {t('continue')}
+            </Button>
+          </form>
+        </CardContent>
+      </Card>
+    </div>
+  )
+}

package/src/components/done-screen.tsx

@@ -0,0 +1,30 @@
+import { useContext } from '@owlmeans/client'
+import type { RoutedComponent } from '@owlmeans/client'
+import { useI18nLib } from '@owlmeans/client-i18n'
+import { OAUTH_I18N } from '../consts.js'
+import { Card, CardContent, CardHeader, CardTitle } from '../@/components/ui/card.js'
+
+/**
+ * The final screen of the device grant — the moment the person's part is finished and the MCP's
+ * poll is expected to catch up within the device-authorization's own poll interval. There is
+ * nothing here to click and nowhere further to go; the tab's only remaining job is to be closed.
+ */
+export const OAuthDoneScreen: RoutedComponent = () => {
+  const context = useContext()
+  const [query] = context.router().useSearchParams()
+  const t = useI18nLib(OAUTH_I18N, 'done')
+  const kind = query.get('kind')
+
+  return (
+    <div style={{ minHeight: '100dvh', display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 16 }}>
+      <Card style={{ width: '100%', maxWidth: 380, textAlign: 'center' }} data-testid="oauth-done-card">
+        <CardHeader>
+          <CardTitle>{t('title')}</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <p>{kind === 'device' ? t('device-message') : t('message')}</p>
+        </CardContent>
+      </Card>
+    </div>
+  )
+}

package/src/components/index.ts

@@ -0,0 +1,3 @@
+export * from './consent-screen.js'
+export * from './device-screen.js'
+export * from './done-screen.js'

package/src/consts.ts

@@ -0,0 +1,6 @@
+/** The lib-tier i18n resource this package registers its strings under. */
+export const OAUTH_I18N = 'oauth'
+
+/** How long a consent screen's suspended sign-in stays valid — generous enough for a person to
+ * pick a provider and come back, short enough that a stale suspension is not a lingering hazard. */
+export const OAUTH_SUSPEND_TTL_MS = 10 * 60 * 1000

package/src/entrypoints.ts

@@ -0,0 +1,22 @@
+import { handler } from '@owlmeans/client'
+import { bindScreen } from '@owlmeans/client-entrypoint'
+import { makeOAuthProtocols } from '@owlmeans/oauth'
+import type { OAuthEntrypointOptions } from '@owlmeans/oauth'
+import { OAuthConsentScreen } from './components/consent-screen.js'
+import { OAuthDeviceScreen } from './components/device-screen.js'
+import { OAuthDoneScreen } from './components/done-screen.js'
+
+/**
+ * The three screens, bound to their components and ready to spread into an application's
+ * entrypoint list — the whole of what a web app has to do beyond calling `appendOAuthScreens`
+ * and configuring the server package with matching aliases.
+ */
+export const oauthEntrypoints = (opts?: OAuthEntrypointOptions) => {
+  const protocols = makeOAuthProtocols(opts)
+
+  return [
+    bindScreen(protocols.consentScreen, handler(OAuthConsentScreen)),
+    bindScreen(protocols.deviceScreen, handler(OAuthDeviceScreen)),
+    bindScreen(protocols.doneScreen, handler(OAuthDoneScreen)),
+  ]
+}