# Website Auth SDK

Shared browser authentication flow and same-origin Cloudflare Pages facade.
Websites retain their own UI; the SDK owns authentication state and navigation.
Native apps, desktop apps and extensions use their own platform contracts.

Public SDK documentation: https://website-auth-sdk.pages.dev/example.
The same Pages site distributes the configuration documents linked below.
Documentation generation runs only in the native Pages build; no SDK runtime,
authentication route, secret or Service Binding is hosted by that project.

## Browser integration

Use `createWebsiteAuthFlow` and subscribe the existing UI to its state.
The [flow contract and example](configuration/FLOW.md) document configuration,
commands, lifecycle, errors and remote verification.
The browser transport factory is internal and is not a supported public import.

## Pages integration

```js
import { createCookiePagesAuthHandler } from 'website-auth-sdk/cloudflare-pages';
export const onRequest = createCookiePagesAuthHandler({
  appSlug: 'your-product',
  bindingName: 'AUTH_SUPABASE_APP',
});
```

The Pages handler owns HttpOnly cookies and calls the authentication Worker
through its private binding. Browser requests stay on `/api/auth`. Tokens never
enter browser storage. `persistSession: false` also disables storage of public
session metadata and uses a short-lived HttpOnly OAuth pending cookie.

The authentication Worker's [example](https://auth-supabase-app.agentcore.workers.dev/example)
owns the central HTTP contracts. Password recovery has a separate HttpOnly grant;
see [recovery configuration](configuration/RECOVERY.md).

For restricted test websites, set `allowedEmail: 'a44238587@gmail.com'` on
both the auth handler and `createPagesWebsiteGuard`. Install the latter as
root Pages middleware with exact public login paths. `createPagesAccessGuard`
also protects individual Pages operations. This restriction is opt-in and does not change
product website access. See the [owner-access contract](configuration/FLOW.md#website-specific-owner-access).

## Optional guest integration

Use `website-auth-sdk/guest` for lazy guest identity issuance, expiration and
observable state. `website-auth-sdk/guest-pages` supplies the same-origin issuance
facade bound to the private `GuestAuth` entrypoint. See the
[guest contract and example](configuration/GUEST.md). Guest credentials remain
memory-only and never replace authenticated account cookies. Initialization does
not issue requests; the product invokes guests only on explicit interactions.

## Package distribution

Consumers pin an immutable package archive, its SHA-256 sidecar and lockfile.
Plain JavaScript builds copy the complete packaged ESM graph, preserving relative
imports. Consumer projects never maintain editable copies of SDK implementation.

Version 1 requires the shared flow. Validate each immutable release in the
Dictum test website’s remote Full build before updating production consumers.