@hadoku/worker-utils 0.0.0-stage → 1.6.20

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 WolffM
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,335 @@
-# Temporary Holding Version
+# Worker Utilities - Quick Reference
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared utilities for Cloudflare Workers. Generic, reusable patterns extracted from production workers.
+
+**Import:** `import { ... } from '@wolffm/worker-utils'`
+
+---
+
+## Files
+
+```text
+workers/shared/
+├── types.ts        # TypeScript type definitions
+├── auth.ts         # Authentication middleware
+├── context.ts      # Request context extraction
+├── validation.ts   # Input validation
+├── cors.ts         # CORS configuration
+├── logging.ts      # Structured logging
+├── masking.ts      # Data masking for safe logging
+├── responses.ts    # HTTP response helpers
+└── index.ts        # Barrel export
+```
+
+---
+
+## auth.ts
+
+**Edge-verified authentication:**
+
+A worker does NOT resolve keys. edge-router resolves the caller against its KV
+key registry, then stamps `X-Hadoku-Tier` alongside an `X-Edge-Auth` provenance
+header; `createEdgeAuth` verifies the provenance against `EDGE_AUTH_SECRET`
+before trusting the tier, and degrades to `public` when it doesn't verify.
+Tier priority: `admin > service > friend > public`. `service` is for
+worker-to-worker / sibling-app traffic.
+
+> **Removed in 1.3.0:** `createHadokuAuth`, `HadokuAuthEnv`, `parseKeysFromEnv`,
+> `parseKeysWithNames`, `validateKeyAndGetType`. They read the `ADMIN_KEYS` /
+> `SERVICE_KEYS` / `FRIEND_KEYS` env arrays, which were retired 2026-07-26 —
+> so they had already stopped authenticating anyone. `createEdgeAuth` is a
+> drop-in (same context shape, same `extend` option).
+
+```typescript
+// Standard hadoku ecosystem auth:
+import { createEdgeAuth } from '@wolffm/worker-utils';
+
+app.use('*', createEdgeAuth());
+//          ↑ verifies X-Edge-Auth, then trusts the edge-stamped X-Hadoku-Tier
+
+// Generic helper (single-key-per-tier case only):
+app.use(
+  '*',
+  createKeyAuth((env) => ({
+    [env.SOME_SINGLE_KEY]: 'admin',
+  }))
+);
+```
+
+**Functions:**
+
+- `createKeyAuth(keyMap, options?)` - Simple key → userType mapping
+- `createAuthMiddleware(config)` - Custom auth logic
+- `validateKeyAndGetType(key, adminKeys, friendKeys, serviceKeys?)` - Validate key & return userType (4-arg form opts into the `'service'` tier)
+- `parseKeysFromEnv(jsonString)` - Parse key config from env vars
+- `getAuthContext(c)` - Get auth from context
+- `requireMinTier('friend')` - Gate a route at a MINIMUM tier (`public < friend < service < wife < admin`); every higher tier is admitted by rank
+- `tierAtLeast(auth, 'admin')` - Same rank check for an already-resolved auth context, for in-handler branching. Never compare `auth.userType` to a string
+- `TIER_RANK` / `Tier` - The rank table and tier union, shared by the edge gate and the in-worker gate
+- ~~`requireUserType([...])`~~ - **Removed** 2026-07-25. Translate to `requireMinTier(<lowest tier in the list>)`
+
+**Adds to context:** `c.get('authContext')` → `{ userType, isAdmin, isFriend, isPublic }`
+
+---
+
+## masking.ts
+
+**Mask sensitive data for logging:**
+
+```typescript
+logRequest('POST', '/session/create', {
+  sessionId: maskSessionId(sessionId), // "1a2b3c4d5e6f7g8h"
+  key: maskKey(authKey), // "admin-secre" (50%)
+});
+```
+
+**Functions:**
+
+- `maskKey(key, percentage?)` - Mask key (show first 50% by default, no suffix)
+- `maskSessionId(id)` - Mask session ID (show first 16 chars, no suffix)
+- `maskEmail(email)` - Mask email (show first char + domain)
+- `redactFields(obj, fields)` - Redact sensitive fields from objects
+
+**Constants:**
+
+- `MASKING.KEY_PERCENTAGE` - Percentage of key to show (0.5 = 50%)
+- `MASKING.KEY_MIN_LENGTH` - Minimum characters to show (4)
+- `MASKING.SESSION_ID_PREFIX_LENGTH` - Default session ID prefix (16)
+- `SENSITIVE_FIELDS` - Common sensitive field names
+
+**Examples:**
+
+```typescript
+maskKey('admin-secret-key-123'); // "admin-secre"
+maskSessionId('1a2b3c4d5e6f7g8h9i0j'); // "1a2b3c4d5e6f7g8h"
+maskEmail('john@example.com'); // "j***@example.com"
+
+redactFields({ username: 'john', password: 'secret' }, ['password']);
+// { username: 'john', password: '[REDACTED]' }
+```
+
+---
+
+**Extract common fields:**
+
+```typescript
+const { userId, sessionId } = extractUserContext(c);
+const boardId = extractField(c, ['query:boardId', 'body:boardId'], 'main');
+```
+
+**Functions:**
+
+- `extractUserContext(c)` - Get userId, sessionId
+- `extractField(c, sources, default?, transform?)` - Single field from multiple sources
+- `extractContext(c, config)` - Multiple fields at once
+- `extractPagination(c)` - Get page, limit, offset
+- `extractSorting(c)` - Get sortBy, sortOrder
+- `getRequestMetadata(c)` - Get IP, userAgent, country, etc.
+
+**Source format:** `'header:X-User-Id'`, `'query:boardId'`, `'body:title'`
+
+---
+
+## validation.ts
+
+**Validate request data:**
+
+```typescript
+const validation = validateFields(body, [
+  { field: 'id', required: true, type: 'string' },
+  { field: 'title', required: true, minLength: 1, maxLength: 200 },
+]);
+if (!validation.valid) return validationError(c, validation.errors);
+```
+
+**Functions:**
+
+- `validateFields(data, rules)` - Full validation with rules
+- `requireFields(data, ['id', 'title'])` - Quick required check
+- `validateBody(rules)` - Middleware for auto-validation
+- `createValidator(rules)` - Reusable validator function
+
+**CommonRules:**
+
+- `CommonRules.id()` - UUID validation
+- `CommonRules.title({ maxLength })` - String 1-200 chars
+- `CommonRules.email(required)` - Email pattern
+- `CommonRules.url(required)` - URL pattern
+- `CommonRules.enum('status', ['active', 'inactive'])` - Enum validation
+- `CommonRules.array('tags', options)` - Array validation
+- `CommonRules.number('age', { min, max, integer })` - Number constraints
+
+---
+
+## cors.ts
+
+**Standard Hadoku CORS:**
+
+```typescript
+app.use('*', createHadokuCors());
+```
+
+**Functions:**
+
+- `createHadokuCors(additionalOrigins?)` - Hadoku defaults + custom
+- `createCorsMiddleware(config)` - Full custom config
+- `matchOrigin(origin, pattern)` - Wildcard matching
+
+**Presets:**
+
+- `CORSPresets.hadoku` - Production Hadoku origins
+- `CORSPresets.development` - Includes localhost
+- `CORSPresets.production(origins)` - Custom production
+- `CORSPresets.publicApi` - Public API (all origins)
+
+---
+
+## logging.ts
+
+**Log requests and errors:**
+
+```typescript
+logRequest('GET', '/api/items', { userId, boardId });
+logError('POST', '/api/items', 'Validation failed', { errors });
+```
+
+**Functions:**
+
+- `logRequest(method, path, context?, level?)` - Log HTTP requests
+- `logError(method, path, error, context?)` - Log errors
+- `createLogger(config)` - Custom logger instance
+- `createRequestLogger(method, path, baseContext)` - Request-scoped logger
+- `startTimer()` - Performance timing (`timer.end(message, context)`)
+- `redactFields(obj, fields)` - Remove sensitive data
+
+**Constants:**
+
+- `SENSITIVE_FIELDS` - Common sensitive field names (password, apiKey, token, etc.)
+
+---
+
+## responses.ts
+
+**Standard HTTP responses:**
+
+```typescript
+return ok(c, { items });
+return created(c, { item });
+return badRequest(c, 'Missing field: id');
+return notFound(c, 'Task');
+```
+
+**Success:**
+
+- `ok(c, data, message?)` - 200
+- `created(c, data, message?)` - 201
+- `noContent(c)` - 204
+
+**Errors:**
+
+- `badRequest(c, message, details?)` - 400
+- `unauthorized(c, message?)` - 401
+- `forbidden(c, message?)` - 403
+- `notFound(c, resource?)` - 404
+- `conflict(c, message, details?)` - 409
+- `serverError(c, message, details?)` - 500
+- `validationError(c, errors)` - 400 with validation details
+
+**Health & Error Handling:**
+
+- `healthCheck(c, service, checks?)` - Health check response
+- `createHealthCheckHandler(service, config)` - Health check handler factory
+- `handleError(c, error, message)` - Generic error handler
+- `withErrorHandling(handler)` - Async error wrapper
+
+---
+
+## types.ts
+
+**Import types:**
+
+```typescript
+import type {
+  UserType, // 'admin' | 'service' | 'friend' | 'public'
+  AuthContext, // { userType, userId?, isAdmin, isFriend, isPublic }
+  ValidationRule, // { field, required?, type?, minLength?, ... }
+  ValidationResult, // { valid, errors }
+  LoggerConfig, // { prefix?, minLevel?, includeTimestamp? }
+  CORSConfig, // { origins, methods, allowedHeaders, ... }
+} from '@wolffm/worker-utils';
+```
+
+---
+
+## Common Patterns
+
+### Minimal Worker
+
+```typescript
+import { Hono } from 'hono';
+import {
+  createKeyAuth,
+  createHadokuCors,
+  extractUserContext,
+  ok,
+} from '@wolffm/worker-utils';
+
+const app = new Hono();
+
+app.use('*', createHadokuCors());
+app.use('*', createEdgeAuth());
+//             ↑ verifies X-Edge-Auth, trusts the edge-stamped tier
+
+app.get('/api/items', async (c) => {
+  const { userId } = extractUserContext(c);
+  const items = await getItems(userId);
+  return ok(c, { items });
+});
+
+export default app;
+```
+
+### With Validation
+
+```typescript
+app.post('/api/items', async (c) => {
+  const body = await c.req.json();
+
+  const validation = validateFields(body, [
+    CommonRules.id(),
+    CommonRules.title({ maxLength: 200 }),
+  ]);
+
+  if (!validation.valid) {
+    return validationError(c, validation.errors);
+  }
+
+  const item = await createItem(body);
+  return created(c, { item });
+});
+```
+
+### With Logging
+
+```typescript
+app.post('/api/items', async (c) => {
+  const { userId } = extractUserContext(c);
+  logRequest('POST', '/api/items', { userId });
+
+  try {
+    const item = await createItem(body);
+    return created(c, { item });
+  } catch (error) {
+    logError('POST', '/api/items', error.message, { userId });
+    return serverError(c, 'Failed to create item');
+  }
+});
+```
+
+---
+
+## See Also
+
+- **[WORKERS.md](../WORKERS.md)** - Worker index and setup guide
+- **[docs/child-apps/NEW_CHILD_APP_CHECKLIST.md](../../docs/child-apps/NEW_CHILD_APP_CHECKLIST.md)** - Backend worker setup (see "Optional: Backend API" section)
+- **[AGENTS.md](../../AGENTS.md)** - Worker debugging and common patterns

package/dist/auth.d.ts

@@ -0,0 +1,153 @@
+import { Context, MiddlewareHandler } from 'hono';
+import { AuthContext } from './types.js';
+
+/**
+ * The Hadoku tier model, and the helpers that read it off a Hono context.
+ *
+ * Workers do NOT authenticate anyone. edge-router resolves the caller against
+ * its KV key registry, stamps `X-Hadoku-Tier` alongside an `X-Edge-Auth`
+ * provenance header, and `createEdgeAuth` (edgeAuth.ts) verifies the
+ * provenance before trusting the tier — degrading to `public` when it doesn't.
+ * That is the only auth middleware in this package.
+ *
+ * What used to live here — `createAuthMiddleware`, `createHadokuAuth`,
+ * `parseKeysFromEnv`, `validateKeyAndGetType` — resolved a caller by parsing
+ * the ADMIN_KEYS / FRIEND_KEYS / SERVICE_KEYS env bindings. Those bindings
+ * were retired on 2026-07-26, so the code had already stopped authenticating
+ * anyone; it was removed in 1.3.0 rather than left exported looking like
+ * working auth. See workers/shared/AGENTS.md.
+ *
+ * What's left is the part every worker still needs: `TIER_RANK` (the single
+ * source of the `public < member < friend < service < wife < admin` ordering, shared with
+ * edge-router's route gate), `tierAtLeast`, `requireMinTier`, and
+ * `getAuthContext`.
+ */
+
+/**
+ * Get auth context from Hono context
+ *
+ * @param c - Hono context
+ * @param contextKey - Key where auth context is stored
+ * @returns Auth context
+ */
+declare function getAuthContext(c: Context, contextKey?: string): AuthContext;
+/**
+ * The Hadoku tier hierarchy. Each tier supersedes every tier below it:
+ * `public < member < friend < service < wife < admin`. A higher tier is admitted
+ * anywhere a lower tier is — service and admin can reach a friend-gated route,
+ * admin can reach a service-gated route, etc. Access is by rank, never an
+ * ad-hoc list.
+ *
+ * The NUMBERS are meaningless on their own; only their ORDER is load-bearing.
+ * Nothing persists a rank — the registry stores the tier NAME and every
+ * comparison re-derives the rank from this table — so inserting a tier in the
+ * middle (as `wife` was on 2026-08-04, between service and admin, and `member`
+ * on 2026-10-29, between public and friend) is a renumbering, not a migration.
+ *
+ * `member` is a person who signed themselves up (a passkey, no handed-out key;
+ * docs/planning/member-tier-2026-10-28.md). Only cardtable admits them; every
+ * other private app stays at `friend`, which they do not reach.
+ *
+ * A CALLER tier not in this table ranks as `public` — see {@link tierAtLeast}.
+ */
+declare const TIER_RANK: Record<string, number>;
+type Tier = 'public' | 'member' | 'friend' | 'service' | 'wife' | 'admin';
+/**
+ * Rank comparison for an already-resolved auth context — the in-handler
+ * counterpart to {@link requireMinTier}.
+ *
+ * Use this instead of comparing `auth.userType` to a string. A direct
+ * `auth.userType === 'admin'` (or `!== 'friend'`) breaks the hierarchy: it
+ * locks a higher tier out of a lower tier's branch, which is exactly the bug
+ * the tier model exists to prevent. `tierAtLeast(auth, 'friend')` admits
+ * friend, service, wife, and admin.
+ *
+ * An unknown or absent caller tier ranks as `public`: admitted where anyone is,
+ * nowhere else. That is still fail-closed for every gated route, and it means
+ * a tier this bundle has never heard of is a guest rather than a refusal — so a
+ * stale consumer serves a new tier's public pages instead of 403ing them, and
+ * the next tier added does not need every app upgraded in lockstep. Until
+ * 1.6.0 an unknown tier ranked -1, below public.
+ *
+ * An unknown REQUIRED tier throws: that is a typo in a gate, and refusing
+ * everyone or admitting everyone would both hide it.
+ *
+ * @example
+ * ```typescript
+ * const auth = getAuthContext(c);
+ * if (!tierAtLeast(auth, 'admin')) return c.json({ error: 'Forbidden' }, 403);
+ *
+ * // Branch on tier inside a handler that serves several tiers:
+ * const rows = tierAtLeast(auth, 'admin') ? await allRows() : await ownRows(auth);
+ * ```
+ */
+declare function tierAtLeast(auth: {
+    userType?: string;
+} | null | undefined, minTier: Tier): boolean;
+/**
+ * Create middleware that requires a MINIMUM tier — the preferred, hierarchy-
+ * aware way to gate a route. Any caller at `minTier` or above is admitted
+ * (`public < member < friend < service < wife < admin`), so `requireMinTier('friend')`
+ * lets friend, service, wife, and admin through. Use this instead of hardcoding
+ * an allowlist; it expresses intent ("friend and up") and can never accidentally
+ * lock out a higher tier.
+ *
+ * @example
+ * ```typescript
+ * app.use('/profiles/*', requireMinTier('friend'));  // friend, service, wife, admin
+ * app.use('/ingest', requireMinTier('service'));     // service, wife, admin
+ * app.use('/wife/*', requireMinTier('wife'));        // wife, admin
+ * app.use('/admin/*', requireMinTier('admin'));      // admin only
+ * ```
+ */
+declare function requireMinTier(minTier: Tier, options?: {
+    contextKey?: string;
+    errorMessage?: string;
+    errorStatus?: number;
+}): MiddlewareHandler;
+/**
+ * Standard auth context for Hadoku APIs
+ *
+ * Used by prompt-api, contact-api, and task-api for consistent auth handling.
+ */
+interface HadokuAuthContext {
+    /**
+     * User permission level. Tier priority is
+     * `admin > wife > service > friend > member > public`.
+     * `service` is for worker-to-worker / sibling-app traffic.
+     */
+    userType: 'admin' | 'wife' | 'service' | 'friend' | 'member' | 'public';
+    /** The credential used for authentication (for audit trails) */
+    credential: string | null;
+    /**
+     * The caller's registry userId, as edge-router resolved it from their key —
+     * set only when edge provenance verified, null otherwise. Prefer this to
+     * reading `X-User-Id` yourself (createEdgeAuth strips an unverified one, but
+     * this field cannot be forged by construction).
+     */
+    userId?: string | null;
+    /** The caller's registry display name, same provenance rule as `userId`. */
+    userName?: string | null;
+}
+/**
+ * Options for the tier-resolving auth middlewares (today: createEdgeAuth).
+ */
+interface HadokuAuthOptions<TExtra extends Record<string, unknown> = Record<string, never>> {
+    /**
+     * Extend the auth context with additional fields.
+     * Receives the base context and returns extra fields to merge.
+     *
+     * @example
+     * ```typescript
+     * createEdgeAuth({
+     *   extend: (base) => ({
+     *     sessionId: base.credential || 'public',
+     *     key: base.credential,
+     *   })
+     * })
+     * ```
+     */
+    extend?: (base: HadokuAuthContext) => TExtra;
+}
+
+export { type HadokuAuthContext, type HadokuAuthOptions, TIER_RANK, type Tier, getAuthContext, requireMinTier, tierAtLeast };

package/dist/auth.js

@@ -0,0 +1,39 @@
+// auth.ts
+function getAuthContext(c, contextKey = "authContext") {
+  return c.get(contextKey);
+}
+var TIER_RANK = {
+  public: 0,
+  member: 1,
+  friend: 2,
+  service: 3,
+  wife: 4,
+  admin: 5
+};
+function tierAtLeast(auth, minTier) {
+  if (!Object.hasOwn(TIER_RANK, minTier)) {
+    throw new Error(`tierAtLeast: unknown required tier '${minTier}'`);
+  }
+  const caller = auth?.userType;
+  const callerRank = caller !== void 0 && Object.hasOwn(TIER_RANK, caller) ? TIER_RANK[caller] : 0;
+  return callerRank >= TIER_RANK[minTier];
+}
+function requireMinTier(minTier, options = {}) {
+  const {
+    contextKey = "authContext",
+    errorMessage = "Insufficient permissions",
+    errorStatus = 403
+  } = options;
+  return async (c, next) => {
+    if (!tierAtLeast(getAuthContext(c, contextKey), minTier)) {
+      return c.json({ error: errorMessage }, errorStatus);
+    }
+    await next();
+  };
+}
+export {
+  TIER_RANK,
+  getAuthContext,
+  requireMinTier,
+  tierAtLeast
+};

package/dist/authPage.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Generic Auth Page
+ *
+ * Renders a simple authentication page for protected routes.
+ * After successful auth, creates a session via /session/create and redirects.
+ * The session cookie is set by the server and used for subsequent requests.
+ *
+ * Progressive enhancement: the form has `action="/session/create"`
+ * `method="POST"` and submits as `application/x-www-form-urlencoded` if the
+ * JS handler doesn't run (content blocker, JS error, transient extension
+ * issue). The /session/create handler accepts both shapes — JSON+header for
+ * the JS-enhanced path, form body for the native-form fallback. Without this
+ * fallback, ANY fetch failure (e.g. iOS content blocker dropping POSTs)
+ * leaves the user with "Load failed" and no recourse.
+ *
+ * Themes: the visitor's theme, as everywhere else on hadoku.me. The page
+ * links /theme-bootstrap.js (spec/theme-bootstrap.js, which sets data-theme
+ * from the `hadoku-theme` storage the apps write) and /themes.css
+ * (@wolffm/themes' own stylesheet); the Astro build emits both
+ * (src/pages/themes.css.ts, src/pages/theme-bootstrap.js.ts). Every colour
+ * below is a theme token with the old fixed palette as its fallback, so the
+ * page still renders where those files are not served.
+ *
+ * Password managers: the key is a password and the form says so in the
+ * vocabulary every manager reads — `autocomplete="current-password"`, a
+ * label, and a hidden `username` field, because managers file a credential
+ * under a username and a key has none (Chrome's and Bitwarden's documented
+ * shape for a password-only form). The WebView in the Android app hands the
+ * same hints to whichever autofill service is installed. The server reads
+ * only `key`, `return`, `fp` and `ft`.
+ *
+ * Device fingerprint (`fp`): a DETECTION signal, never an auth factor. The
+ * page hashes a handful of device traits (screen, timezone, languages,
+ * hardware, canvas and WebGL renders) in the browser and sends only the
+ * digests — the raw values never leave it. edge-router compares them against
+ * the devices that key has signed in from before and flags a stranger (see
+ * workers/edge-router/src/device-ledger.ts). Collection is time-boxed and
+ * every failure degrades to "no fingerprint", so it can never cost a login.
+ */
+interface AuthPageOptions {
+    /** Title shown on the auth page */
+    title?: string;
+    /** Description shown above the form */
+    description?: string;
+    /** The target path to redirect to after auth (defaults to current path) */
+    targetPath?: string;
+    /** Error message shown above the form (from ?error= on the form-fallback path) */
+    errorMessage?: string;
+    /**
+     * Open Graph title/description for link-preview crawlers (Discord, Slack,
+     * iMessage…). Crawlers hitting a gated path receive this sign-in page, so
+     * without these the embed reads "Sign in to Hadoku / Enter your access
+     * key." — pass the APP's identity here so the preview describes the
+     * destination while humans still see the sign-in form. Falls back to
+     * title/description when not given.
+     */
+    ogTitle?: string;
+    ogDescription?: string;
+    /**
+     * Absolute og:image URL for the preview card. Crawlers fetch this with NO
+     * cookies, from their own IPs — so it must resolve for an unauthenticated
+     * caller or the card renders imageless. Supplying it also upgrades the
+     * Twitter card from `summary` to `summary_large_image`.
+     */
+    ogImage?: string;
+    /** Pixel dimensions of ogImage. Let crawlers reserve layout before the fetch. */
+    ogImageWidth?: number;
+    ogImageHeight?: number;
+    /** Canonical og:url for the resource, when it differs from the gated path. */
+    ogUrl?: string;
+    /**
+     * The edge's signed proof that a sign-in came through THIS page (edge-router
+     * auth-funnel.ts). Posted back as `ft` on both the fetch and the native-form
+     * path; `/session/create` refuses a sign-in without one.
+     */
+    funnelToken?: string;
+    /**
+     * Offer sign-up beside sign-in: a name and a new passkey make a member
+     * (edge-router accounts.ts). Only where the destination admits members,
+     * so a stranger is never invited to make an account that gets them nowhere.
+     */
+    signup?: boolean;
+}
+/**
+ * `/auth/sign-in.js`: the sign-in client as an ES module, for an app that
+ * takes a key in its own UI.
+ *
+ *     const { signIn } = await import('/auth/sign-in.js');
+ *     await signIn(key); // throws Error(message) on a refused key
+ *
+ *     if (passkeysSupported()) await signInWithPasskey(); // same, no key
+ *     await addPasskey(); // signed in: save one on this device
+ *     await signUp(name); // a new member account, signed in
+ *
+ * Both passkey calls take `{ signal }` to cancel an open prompt, and give up
+ * on their own after 90s, so a prompt that never answers cannot hang the UI.
+ *
+ * Each throws an Error whose message is fit to show. The funnel token is
+ * fetched per call from `/auth/funnel-token` rather than baked into the module, so a tab left open past the token's life still signs
+ * in through the funnel. Signing in changes who the page is acting for, so the
+ * caller reloads afterwards.
+ */
+declare function renderSignInModule(): string;
+/**
+ * Render a standalone auth page HTML
+ */
+declare function renderAuthPage(options?: AuthPageOptions): string;
+/**
+ * Create an auth page Response
+ */
+declare function authPageResponse(options?: AuthPageOptions): Response;
+
+export { type AuthPageOptions, authPageResponse, renderAuthPage, renderSignInModule };