@synqauth/nextjs 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aerosol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# @synqauth/nextjs
 
-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.
+Synq for Next.js: a backend-for-frontend session, so the browser never holds a Synq token.
+
+Synq is customer identity for businesses: an OpenID Connect issuer for each of your brands, with Solana wallet, social, email and passkey sign-in. The documentation is at [docs.synq.build](https://docs.synq.build).
+
+This package is at 0.x and hasn't been published yet: its API can change in any release until Synq's first customer depends on it.
+
+## Quick start
+
+Register the app in the Synq dashboard as a web app, with `https://<your app>/api/auth/callback` as its redirect URI and `https://<your app>/` as its post-logout URI. Then set five environment variables:
+
+```sh
+SYNQ_ISSUER=https://<your brand>.auth.synq.build
+SYNQ_CLIENT_ID=app_...
+SYNQ_CLIENT_SECRET=...
+SYNQ_APP_URL=https://app.example.com
+SYNQ_SESSION_SECRET=$(openssl rand -base64 32)
+```
+
+One configuration, which the server and the proxy share:
+
+```ts
+// synq.config.ts
+import { defineSynqConfig } from '@synqauth/nextjs/config'
+
+export const synqConfig = defineSynqConfig({})
+```
+
+```ts
+// lib/synq.ts
+import { synqAuth } from '@synqauth/nextjs'
+import { synqConfig } from '../synq.config'
+
+export const synq = synqAuth(synqConfig)
+```
+
+```ts
+// app/api/auth/[...synq]/route.ts
+import { synq } from '@/lib/synq'
+
+export const { GET, POST, PATCH, DELETE } = synq.handlers
+```
+
+```ts
+// proxy.ts
+import { synqProxy } from '@synqauth/nextjs/proxy'
+import { synqConfig } from './synq.config'
+
+export const proxy = synqProxy(synqConfig, { protect: ['/dashboard'] })
+// Pages only: not Next's files, nor anything with an extension.
+export const config = { matcher: ['/((?!_next/|.*\\..*).*)'] }
+```
+
+To add a way to sign in to someone's account (Google, a wallet, anything the brand offers), POST `{ method, returnTo }` as JSON to `/api/auth/link` from your own pages and send the browser to the `redirect` it answers, or call `useAuth().link('google')` from `@synqauth/react`: Synq asks them to sign in again, then adds it.
+
+To sign people in on your own page instead of the brand's (AERO-1411), turn on own-UI sign-in for the app in the dashboard and use `<SignInForm>` or `useSignIn()` from `@synqauth/react`. They post each step to `/api/auth/sign-in/flow`, which takes it to Synq as your app. Pass `clientAddress` to `defineSynqConfig` when your host doesn't set `x-real-ip`, so Synq can limit tries per address. Read a header your own proxy sets, never one the browser could send:
+
+```ts
+export const synqConfig = defineSynqConfig({
+  // Behind Cloudflare
+  clientAddress: (request) => request.headers.get('cf-connecting-ip') ?? undefined,
+})
+```
+
+In a server component, `await synq.me()` is the signed-in person or null, and `await synq.getAccessToken()` is a token for your API (`resource`). Link `synq.signInPath({ returnTo: '/dashboard' })` to sign in, and sign out with a form that POSTs to `synq.signOutPath`.
+
+## When a sign-in doesn't finish
+
+When Synq refuses a sign-in (the person cancelled, their account can't use the app, a token gate they went back from) or the callback fails, the route mount sends the browser back to `returnTo` with `synq_error=<code>`. The proxy never sends such a page to sign in again: with the same session at the brand, that would land on the same refusal, round and round. Without a session, it shows why instead, with "Try again" and "Use another account" (`prompt=select_account`). Give it a page of your own with `signInError`, which it never protects:
+
+```ts
+export const proxy = synqProxy(synqConfig, { protect: () => true, signInError: '/sign-in-error' })
+```
+
+```tsx
+// app/sign-in-error/page.tsx
+export default async function SignInError({ searchParams }: PageProps<'/sign-in-error'>) {
+  const failed = synq.signInError(await searchParams)
+  if (!failed) redirect('/')
+  return (
+    <main>
+      <h1>Sign-in didn’t finish</h1>
+      <p>{failed.message}</p>
+      <a href={failed.retryPath}>Try again</a> <a href={failed.anotherAccountPath}>Use another account</a>
+    </main>
+  )
+}
+```
+
+A page that isn't protected gets `synq_error` as it is: `synq.signInError(await searchParams, '/where-to-come-back')` reads it there too.
+
+Next 16 runs `proxy.ts` on Node. The proxy imports nothing only Node has, so it works on the Edge runtime too.
+
+## More than one server process: use a store
+
+By default a session lives in a sealed, HttpOnly cookie, and only one refresh runs at a time within one server process. Synq rotates refresh tokens and ends a session whose old one comes back, so an app on several processes (Vercel and other serverless hosts, replicas) must keep sessions in a store they all share, which gives each session one lock:
+
+```ts
+import { keyValueSessionStore } from '@synqauth/nextjs'
+
+export const synqConfig = defineSynqConfig({
+  store: keyValueSessionStore({
+    get: (key) => redis.get(key),
+    set: async (key, value, { ttlMs, onlyIfAbsent }) =>
+      (await redis.set(key, value, { PX: ttlMs, NX: onlyIfAbsent })) === 'OK',
+    delete: async (key) => void (await redis.del(key)),
+  }),
+})
+```
+
+`synqAuth()` refuses cookie sessions where `VERCEL`, `AWS_LAMBDA_FUNCTION_NAME`, `NETLIFY`, `K_SERVICE` or `KUBERNETES_SERVICE_HOST` is set, unless `allowSingleProcessCookieMode` says the app truly runs one process. A store also lets your server end a session; a cookie can't be taken back.
+
+To rotate `SYNQ_SESSION_SECRET`, move the old secret to `SYNQ_SESSION_SECRET_PREVIOUS` (comma-separated), which opens cookies but never seals them.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,13 @@
+//#region src/client.d.ts
+/** Calls the app's route mount: `request('session')`, `request('account/v1/profile', { method: 'PATCH', ... })`. */
+export type SynqMountRequest = (path: string, init?: RequestInit) => Promise<Response>;
+/** A browser plugin: actions over its server plugin's routes (`defineSynqPlugin`), which @synqauth/react exposes on `useAuth().plugins`. */
+export interface SynqClientPlugin<Id extends string = string, Actions = unknown> {
+  readonly id: Id;
+  actions(request: SynqMountRequest): Actions;
+}
+/** Declares a browser plugin, its id the same as its server plugin's. */
+export declare function defineSynqClientPlugin<const Id extends string, Actions>(plugin: SynqClientPlugin<Id, Actions>): SynqClientPlugin<Id, Actions>;
+/** A request to `basePath`'s routes from the app's own page: same origin, with the cookie, never cached. */
+export declare function mountRequest(basePath?: string, fetcher?: typeof fetch): SynqMountRequest;
+//#endregion

package/dist/client.js

@@ -0,0 +1,24 @@
+//#region src/client.ts
+/** Declares a browser plugin, its id the same as its server plugin's. */
+function defineSynqClientPlugin(plugin) {
+	if (!/^[a-z][a-z0-9-]{0,39}$/.test(plugin.id)) throw new TypeError(`A Synq plugin's id must be lowercase letters, digits and dashes: ${plugin.id}`);
+	return plugin;
+}
+/** A request to `basePath`'s routes from the app's own page: same origin, with the cookie, never cached. */
+function mountRequest(basePath = "/api/auth", fetcher = fetch) {
+	const base = `/${basePath.replace(/^\/+|\/+$/g, "")}`;
+	return (path, init = {}) => fetcher(`${base}/${path.replace(/^\/+/, "")}`, {
+		...init,
+		credentials: "same-origin",
+		cache: "no-store",
+		headers: {
+			accept: "application/json",
+			...headersOf(init.headers)
+		}
+	});
+}
+function headersOf(headers) {
+	return Object.fromEntries(new Headers(headers).entries());
+}
+//#endregion
+export { defineSynqClientPlugin, mountRequest };

package/dist/config-CpEbAGEs.d.ts

@@ -0,0 +1,215 @@
+//#region src/plugins.d.ts
+/** A signed-in person, from the ID token Synq issued at sign-in. */
+interface SynqUser {
+  /** The user's id at the brand (`usr_…`). */
+  readonly sub: string;
+  readonly email?: string;
+  readonly email_verified?: boolean;
+  readonly name?: string;
+  readonly preferred_username?: string;
+  readonly picture?: string;
+  /** When they signed in, in seconds since the epoch. */
+  readonly auth_time?: number;
+  /** How they signed in: `pwd`, `otp`, `wallet`, `hwk`, `fed`... */
+  readonly amr?: readonly string[];
+  readonly [claim: string]: unknown;
+}
+/** What a plugin's route is handed. */
+interface SynqPluginContext {
+  /** The signed-in person, or null. */
+  user(): Promise<SynqUser | null>;
+  /** A current access token for `resource` (the session's main API by default), refreshed when it must be. */
+  getAccessToken(options?: {
+    resource?: string;
+  }): Promise<string>;
+  readonly issuer: string;
+  readonly clientId: string;
+  readonly basePath: string;
+}
+/** A route: `GET /status`, `POST /verify`... relative to the plugin's own path. */
+type SynqPluginRoute = (context: SynqPluginContext, request: Request) => Response | Promise<Response>;
+/** A server plugin: routes under the route mount, at `<basePath>/<id>/…`. Declare one with `defineSynqPlugin`. */
+interface SynqPlugin {
+  /** Where its routes are, under the route mount: lowercase letters, digits and dashes. */
+  readonly id: string;
+  /** Its routes, keyed `"<METHOD> /<path>"`: GET, POST, PATCH or DELETE, the methods the route mount exports. */
+  readonly routes?: Readonly<Record<string, SynqPluginRoute>>;
+}
+/** Declares a server plugin, checking its id and routes once, when the module loads. */
+declare function defineSynqPlugin<const T extends SynqPlugin>(plugin: T): T;
+//#endregion
+//#region src/store.d.ts
+/** What a session keeps: tokens per API and the refresh token, as strings. */
+type SessionValues = Record<string, string>;
+/**
+ * Where sessions live server-side when the cookie holds only the session's
+ * id (`synqAuth({ store })`): needed where several processes serve the app.
+ * `keyValueSessionStore` makes one from any key-value store.
+ */
+interface SynqSessionStore {
+  get(id: string): Promise<SessionValues | null>;
+  set(id: string, values: SessionValues, maxAgeSeconds: number): Promise<void>;
+  delete(id: string): Promise<void>;
+  /** Runs `fn` while no other holder of `id`'s lock does, in any process sharing the store. */
+  lock<T>(id: string, fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * A store in this process's memory: for tests and a single server process,
+ * where the default cookie does as well.
+ */
+declare function memorySessionStore(): SynqSessionStore;
+/** The few operations a key-value store (Redis, Valkey, Upstash...) gives `keyValueSessionStore`. */
+interface KeyValue {
+  get(key: string): Promise<string | null | undefined>;
+  /** Sets `key`, expiring after `ttlMs`; with `onlyIfAbsent`, only when it isn't set (Redis `SET … NX PX`), and says whether it did. */
+  set(key: string, value: string, options: {
+    ttlMs: number;
+    onlyIfAbsent?: boolean;
+  }): Promise<boolean>;
+  delete(key: string): Promise<void>;
+  /**
+   * Deletes `key` only while it holds `value`, in one step: how a lock's
+   * holder releases it and never another's. In Redis, a script:
+   *
+   * ```lua
+   * if redis.call('get', KEYS[1]) == ARGV[1] then return redis.call('del', KEYS[1]) end
+   * return 0
+   * ```
+   *
+   * Without it the lock reads then deletes, and a lock that expired between
+   * the two, and was taken by another request, could be deleted.
+   */
+  deleteIfEquals?(key: string, value: string): Promise<void>;
+}
+/** What `keyValueSessionStore` takes besides the store itself. */
+interface KeyValueSessionStoreOptions {
+  /** Prefix for every key: `synq:` by default. */
+  prefix?: string;
+  /**
+   * Milliseconds a lock is held at most, should its holder die: 30 seconds by
+   * default, and always longer than a request to Synq may take (10 seconds),
+   * so a slow refresh never outlives its lock.
+   */
+  lockTtlMs?: number;
+  /** Milliseconds to wait for a lock before giving up with `lock_timeout`: 35 seconds by default, past a dead holder's lock. */
+  lockWaitMs?: number;
+}
+/**
+ * Sessions in a key-value store every server process shares, such as Redis
+ * or Valkey: the store an app on several processes (replicas, serverless
+ * functions) needs. Its lock is `SET … NX PX` with a token, polled until
+ * free, and released only by its holder; it expires on its own, so a dead
+ * process never holds a session for ever.
+ *
+ * ```ts
+ * keyValueSessionStore({
+ *   get: (key) => redis.get(key),
+ *   set: async (key, value, { ttlMs, onlyIfAbsent }) =>
+ *     (await redis.set(key, value, { PX: ttlMs, NX: onlyIfAbsent })) === 'OK',
+ *   delete: async (key) => void (await redis.del(key)),
+ * })
+ * ```
+ */
+declare function keyValueSessionStore(kv: KeyValue, options?: KeyValueSessionStoreOptions): SynqSessionStore;
+//#endregion
+//#region src/config.d.ts
+/**
+ * What `synqAuth()` and `defineSynqConfig()` take. Every option the
+ * environment can give (`SYNQ_*`) is optional here; an option given wins.
+ */
+interface SynqAuthOptions {
+  /** The brand's issuer URL (`SYNQ_ISSUER`): `https://<issuer-slug>.auth.<Synq's domain>`. */
+  issuer?: string;
+  /** The app's client_id (`SYNQ_CLIENT_ID`): a web app, the brand's own. */
+  clientId?: string;
+  /** The app's client secret (`SYNQ_CLIENT_SECRET`). Never reaches the browser. */
+  clientSecret?: string;
+  /** Where the app is served (`SYNQ_APP_URL`), such as `https://app.example.com`: the callback and post-logout URIs are made from it. */
+  appUrl?: string;
+  /** At least 32 random bytes (`SYNQ_SESSION_SECRET`) the session's cookies are sealed with. */
+  sessionSecret?: string;
+  /**
+   * Secrets cookies may still be sealed with (`SYNQ_SESSION_SECRET_PREVIOUS`,
+   * comma-separated): to rotate the secret, move the old one here, and drop
+   * it once every session it sealed has ended. Nothing is sealed with them.
+   */
+  previousSessionSecrets?: readonly string[];
+  /** Where the route mount is: `/api/auth` by default, for `app/api/auth/[...synq]/route.ts`. */
+  basePath?: string;
+  /** The app's own API, a registered API's identifier: the session's access token is for it. */
+  resource?: string;
+  /**
+   * Whether the session also holds a token for the brand's account API
+   * (`<issuer>/me`), which `<basePath>/account/*` calls with, for
+   * @synqauth/react's profile, wallets and sessions: true by default. Only
+   * the brand's own apps may have one.
+   */
+  account?: boolean;
+  /** Scopes beyond `openid profile email offline_access` (and the account API's, when `account`): the app's API's scopes, say. */
+  scope?: string;
+  /** Where the browser lands after signing out: the app's root by default. Register it as a post-logout URI, exactly. */
+  postLogoutRedirectUri?: string;
+  /**
+   * Where tokens are kept: in the session's sealed cookie by default, or in
+   * this store, with only the session's sealed id in the cookie. An app on
+   * more than one server process (replicas, serverless) needs a store with
+   * a lock shared by all of them, or two requests may refresh at once and
+   * Synq ends the session (see `keyValueSessionStore`). A store also lets
+   * the app end a session on its server; a cookie can't be taken back.
+   */
+  store?: SynqSessionStore;
+  /**
+   * Keep sessions in the cookie although the environment looks like several
+   * server processes (Vercel, Lambda, Netlify, Cloud Run, Kubernetes): only
+   * for an app that truly runs one. Without a store there, two processes
+   * refresh one session at once and Synq signs the person out.
+   */
+  allowSingleProcessCookieMode?: boolean;
+  /** Seconds a session lasts at most, however it's refreshed: 30 days by default. */
+  sessionMaxAge?: number;
+  /** Seconds before an access token expires it's refreshed: 30 by default. */
+  refreshLeewaySeconds?: number;
+  /** Routes and hooks other @synqauth packages add under the route mount. */
+  plugins?: readonly SynqPlugin[];
+  /** The `fetch` to call Synq with. */
+  fetch?: typeof fetch;
+  /**
+   * Where the person signing in on the app's own screens is
+   * (`<basePath>/sign-in/flow`, AERO-1411), as this server saw them: Synq
+   * counts its per-address limits for the app with it (`Synq-End-User-IP`).
+   * `x-real-ip` by default, which Vercel sets; give one that reads your
+   * proxy's header otherwise. Return undefined, and per-address protection
+   * is off for the app.
+   */
+  clientAddress?: (request: Request) => string | undefined;
+}
+interface SynqConfig {
+  readonly issuer: string;
+  readonly clientId: string;
+  readonly clientSecret: string;
+  readonly appUrl: URL;
+  readonly sessionSecret: string;
+  readonly previousSessionSecrets: readonly string[];
+  readonly basePath: string;
+  /** The resource the session's main token is for: the app's API, else the account API, else none. */
+  readonly primary: string | undefined;
+  /** The account API's identifier, when the session has a token for it. */
+  readonly accountApi: string | undefined;
+  readonly scope: string;
+  readonly redirectUri: string;
+  readonly postLogoutRedirectUri: string;
+  readonly store: SynqSessionStore | undefined;
+  readonly sessionMaxAge: number;
+  readonly refreshLeewaySeconds: number;
+  readonly plugins: readonly SynqPlugin[];
+  readonly fetch: typeof fetch | undefined;
+  /** Where a person signing in on the app's own screens is: `x-real-ip` by default. */
+  readonly clientAddress: (request: Request) => string | undefined;
+  /** Over https: `Secure` cookies with the `__Host-` prefix. */
+  readonly secure: boolean;
+}
+type Env = Record<string, string | undefined>;
+/** The configuration from `options` and the environment; throws `invalid_options` for anything missing or unsafe. */
+declare function resolveConfig(options?: SynqAuthOptions, env?: Env): SynqConfig;
+//#endregion
+export { KeyValueSessionStoreOptions as a, keyValueSessionStore as c, SynqPluginContext as d, SynqPluginRoute as f, KeyValue as i, memorySessionStore as l, defineSynqPlugin as m, SynqConfig as n, SessionValues as o, SynqUser as p, resolveConfig as r, SynqSessionStore as s, SynqAuthOptions as t, SynqPlugin as u };

package/dist/define.d.ts

@@ -0,0 +1,6 @@
+import { t as SynqAuthOptions } from "./config-CpEbAGEs.js";
+//#region src/define.d.ts
+/** Declares the app's Synq configuration: `SYNQ_*` environment variables fill in whatever it leaves out. */
+export declare function defineSynqConfig<const T extends SynqAuthOptions>(options: T): T;
+//#endregion
+export type { SynqAuthOptions };

package/dist/define.js

@@ -0,0 +1,7 @@
+//#region src/define.ts
+/** Declares the app's Synq configuration: `SYNQ_*` environment variables fill in whatever it leaves out. */
+function defineSynqConfig(options) {
+	return options;
+}
+//#endregion
+export { defineSynqConfig };

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+import { a as KeyValueSessionStoreOptions, c as keyValueSessionStore, d as SynqPluginContext, f as SynqPluginRoute, i as KeyValue, l as memorySessionStore, m as defineSynqPlugin, n as SynqConfig, o as SessionValues, p as SynqUser, r as resolveConfig, s as SynqSessionStore, t as SynqAuthOptions, u as SynqPlugin } from "./config-CpEbAGEs.js";
+import { defineSynqConfig } from "./define.js";
+import { cookies } from "next/headers.js";
+//#region src/cookies.d.ts
+/** The cookies a request carries and the changes a response makes: what a route handler, Next's `cookies()` or a test gives. */
+interface CookieJar {
+  get(name: string): string | undefined;
+  /** Every cookie name the request carries. */
+  names(): Iterable<string>;
+  set(name: string, value: string, options: CookieOptions): void;
+  delete(name: string, options: Pick<CookieOptions, 'secure'>): void;
+  /** Whether a change reaches the browser: false in a server component, where cookies are read-only. Writable when absent. */
+  writable?(): boolean;
+}
+interface CookieOptions {
+  /** Seconds the browser keeps it; a session cookie when undefined. */
+  maxAge?: number;
+  /** Over https: `Secure`, and the name carries `__Host-`. */
+  secure: boolean;
+}
+//#endregion
+//#region src/core.d.ts
+/** Who is signed in, as the browser may see it: never a token. */
+interface SynqSessionInfo {
+  readonly user: SynqUser | null;
+  /** When the main access token expires, in seconds since the epoch. */
+  readonly expiresAt: number | null;
+}
+interface SynqCore {
+  /** Answers a request under the route mount. */
+  handle(request: Request): Promise<Response>;
+  /** The signed-in person, from the session's ID token: no request to Synq. */
+  user(jar: CookieJar): Promise<SynqUser | null>;
+  session(jar: CookieJar): Promise<SynqSessionInfo>;
+  /** A current access token for `resource` (the session's main API by default), refreshed when it must be. */
+  getAccessToken(jar: CookieJar, options?: {
+    resource?: string;
+    minValiditySeconds?: number;
+  }): Promise<string>;
+  /**
+   * Refreshes the session's main token when it's due, where the cookie can
+   * be written (Next's proxy), so the server components after it never
+   * need to; says whether someone is signed in.
+   */
+  refreshIfDue(jar: CookieJar): Promise<boolean>;
+  readonly config: SynqConfig;
+}
+/**
+ * The framework-neutral core `synqAuth()` runs on, over any cookie jar: for
+ * a server that answers the same routes without Next. Most apps use
+ * `synqAuth()` instead.
+ */
+export declare function createSynqCore(config: SynqConfig): SynqCore;
+//#endregion
+//#region src/sign-in-error.d.ts
+/** The query parameter the route mount adds to `returnTo` when a sign-in fails. */
+export declare const SIGN_IN_ERROR_PARAM = "synq_error";
+/** Why the last sign-in didn't finish, and the ways on. */
+interface SynqSignInError {
+  /** The OAuth or SDK error code (`access_denied`, `unknown_state`…). */
+  readonly code: string;
+  /** What happened, in plain words for the person. */
+  readonly message: string;
+  /** Signs in again, back to the same page. */
+  readonly retryPath: string;
+  /** Signs in as someone else (`prompt=select_account`), back to the same page. */
+  readonly anotherAccountPath: string;
+}
+/** What a sign-in error code means, in plain words. */
+export declare function signInErrorMessage(code: string): string;
+//#endregion
+//#region src/index.d.ts
+/** What `synqAuth()` returns: the route mount's handlers and the server's view of the session. */
+export interface SynqAuth {
+  /** The route mount's handlers, for `app/api/auth/[...synq]/route.ts`. */
+  readonly handlers: {
+    readonly GET: (request: Request) => Promise<Response>;
+    readonly POST: (request: Request) => Promise<Response>;
+    readonly PATCH: (request: Request) => Promise<Response>;
+    readonly DELETE: (request: Request) => Promise<Response>;
+  };
+  /** The signed-in person, or null: read from the session's ID token, once per request, with no request to Synq. */
+  me(): Promise<SynqUser | null>;
+  /** Who is signed in and until when, as the browser may see it. */
+  getSession(): Promise<SynqSessionInfo>;
+  /**
+   * A current access token for the app's API (or `resource`), refreshed
+   * when it must be: for the app's server to call its API with. Never hand
+   * it to the browser.
+   */
+  getAccessToken(options?: {
+    resource?: string;
+    minValiditySeconds?: number;
+  }): Promise<string>;
+  /** Where to send the browser to sign in, coming back to `returnTo`. */
+  signInPath(options?: {
+    returnTo?: string;
+    method?: string;
+    loginHint?: string;
+    prompt?: 'login' | 'none' | 'consent' | 'select_account';
+    maxAge?: number;
+  }): string;
+  /** Where a form POSTs to sign out. */
+  readonly signOutPath: string;
+  /**
+   * Why the last sign-in didn't finish, from a page's search params: the
+   * `synq_error` the route mount adds to `returnTo` when Synq refused or the
+   * callback failed, and the `returnTo` the proxy adds when it rewrites to
+   * its `signInError` page (else `returnTo` here). Its code, plain words
+   * for the person, and the ways on: signing in again, and as someone else.
+   * Null when the page has none.
+   */
+  signInError(searchParams: URLSearchParams | Record<string, string | string[] | undefined>, returnTo?: string): SynqSignInError | null;
+}
+/**
+ * Synq for this app, configured from SYNQ_ISSUER, SYNQ_CLIENT_ID,
+ * SYNQ_CLIENT_SECRET, SYNQ_APP_URL and SYNQ_SESSION_SECRET unless `options`
+ * (`defineSynqConfig`, shared with the proxy) says.
+ */
+export declare function synqAuth(options?: SynqAuthOptions): SynqAuth;
+type NextCookieStore = Awaited<ReturnType<typeof cookies>>;
+/** Next's cookie store as the cookie jar `createSynqCore` reads and writes. */
+export declare function jarOf(store: NextCookieStore): CookieJar;
+//#endregion
+export { type KeyValue, type KeyValueSessionStoreOptions, type SessionValues, type SynqAuthOptions, type SynqPlugin, type SynqPluginContext, type SynqPluginRoute, type SynqSessionInfo, type SynqSessionStore, type SynqSignInError, type SynqUser, defineSynqConfig, defineSynqPlugin, keyValueSessionStore, memorySessionStore, resolveConfig };

package/dist/index.js

@@ -0,0 +1,106 @@
+import { c as memorySessionStore, d as normalizePath, f as resolveConfig, l as defineSynqPlugin, n as signInErrorMessage, o as createSynqCore, r as signInErrorOf, s as keyValueSessionStore, t as SIGN_IN_ERROR_PARAM } from "./sign-in-error-kd56GHt_.js";
+import { defineSynqConfig } from "./define.js";
+import { cookies } from "next/headers.js";
+import { cache } from "react";
+//#region src/index.ts
+/**
+* Synq for this app, configured from SYNQ_ISSUER, SYNQ_CLIENT_ID,
+* SYNQ_CLIENT_SECRET, SYNQ_APP_URL and SYNQ_SESSION_SECRET unless `options`
+* (`defineSynqConfig`, shared with the proxy) says.
+*/
+function synqAuth(options = {}) {
+	let core;
+	const get = () => core ??= createSynqCore(resolveConfig(options));
+	const handler = (request) => get().handle(request);
+	const basePath = () => normalizePath(options.basePath ?? "/api/auth");
+	const me = cache(async () => {
+		const jar = await nextJar();
+		return get().user(jar);
+	});
+	const getSession = cache(async () => {
+		const jar = await nextJar();
+		return get().session(jar);
+	});
+	return {
+		handlers: {
+			GET: handler,
+			POST: handler,
+			PATCH: handler,
+			DELETE: handler
+		},
+		me,
+		getSession,
+		async getAccessToken(opts) {
+			const jar = await nextJar();
+			return get().getAccessToken(jar, opts);
+		},
+		signInPath(opts = {}) {
+			const params = new URLSearchParams();
+			if (opts.returnTo) params.set("returnTo", opts.returnTo);
+			if (opts.method) params.set("method", opts.method);
+			if (opts.loginHint) params.set("login_hint", opts.loginHint);
+			if (opts.prompt) params.set("prompt", opts.prompt);
+			if (opts.maxAge !== void 0) params.set("max_age", String(opts.maxAge));
+			const query = params.toString();
+			return `${basePath()}/sign-in${query ? `?${query}` : ""}`;
+		},
+		get signOutPath() {
+			return `${basePath()}/sign-out`;
+		},
+		signInError(searchParams, returnTo = "/") {
+			const read = (name) => {
+				if (searchParams instanceof URLSearchParams) return searchParams.get(name);
+				const value = searchParams[name];
+				return Array.isArray(value) ? value[0] : value;
+			};
+			return signInErrorOf(read(SIGN_IN_ERROR_PARAM), basePath(), read("returnTo") ?? returnTo);
+		}
+	};
+}
+/**
+* Next's cookies as a jar. A server component can't set cookies, so it says
+* it isn't writable there, and the session never refreshes in one: the
+* proxy refreshes it before the page renders.
+*/
+async function nextJar() {
+	return jarOf(await cookies());
+}
+/** Next's cookie store as the cookie jar `createSynqCore` reads and writes. */
+function jarOf(store) {
+	const write = (name, value, secure, maxAge) => {
+		try {
+			store.set({
+				name,
+				value,
+				httpOnly: true,
+				sameSite: "lax",
+				path: "/",
+				secure,
+				maxAge
+			});
+		} catch {}
+	};
+	let writable;
+	return {
+		get: (name) => store.get(name)?.value,
+		names: () => store.getAll().map((cookie) => cookie.name),
+		set: (name, value, opts) => write(name, value, opts.secure, opts.maxAge),
+		delete: (name, opts) => write(name, "", opts.secure, 0),
+		writable() {
+			if (writable === void 0) try {
+				store.set({
+					name: "synq.probe",
+					value: "",
+					maxAge: 0,
+					path: "/"
+				});
+				writable = true;
+			} catch {
+				writable = false;
+			}
+			return writable;
+		}
+	};
+}
+//#endregion
+export { SIGN_IN_ERROR_PARAM, createSynqCore, defineSynqConfig, defineSynqPlugin, jarOf, keyValueSessionStore, memorySessionStore, resolveConfig, signInErrorMessage, synqAuth };