@nexpress/core 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,640 @@
+import { p as NpAccessFunction, n as NpUserRole, e as NpAuthUser } from './types-TlsbXS0T.js';
+export { F as NpPrincipal } from './types-TlsbXS0T.js';
+import { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { Options } from '@node-rs/argon2';
+
+declare const authenticated: NpAccessFunction;
+declare const isAdmin: NpAccessFunction;
+declare const isEditorOrAbove: NpAccessFunction;
+declare const isOwnerOrAdmin: NpAccessFunction;
+
+/**
+ * Staff-side JWT helpers. Both access (`np-session`) and refresh
+ * (`np-refresh`) cookies are signed with this module; the
+ * `use: "access" | "refresh"` claim separates them so a stolen
+ * refresh JWT cannot be replayed as a session cookie. Without this
+ * separation a leaked 7-day refresh became a 7-day admin bearer
+ * because both cookies decoded to the same `{ sub, role, ver }`
+ * payload through `verifyToken` (#94).
+ *
+ * The fix mirrors the member-side fix from #92/#93: the `use` claim
+ * is required, no legacy fallback for tokens missing the claim. The
+ * cost is one forced re-login for staff sessions issued before the
+ * deploy; bounded by the 7-day refresh TTL.
+ */
+type NpTokenUse = "access" | "refresh";
+interface NpTokenPayload {
+    sub: string;
+    role: NpUserRole;
+    ver: number;
+    /** Required. `verifyToken` refuses tokens missing this claim so
+     *  legacy refresh JWTs cannot be smuggled into the session
+     *  cookie path. */
+    use: NpTokenUse;
+    /** Random per-token id — needed if rotation lands on the staff
+     *  side (mirrors the member-side `jti` for #45). Optional today
+     *  but populated on every newly-minted token. */
+    jti?: string;
+    iat: number;
+    exp: number;
+}
+declare function signToken(user: {
+    id: string;
+    role: NpUserRole;
+    tokenVersion: number;
+}, secret: string, expirationSeconds?: number, tokenUse?: NpTokenUse): Promise<string>;
+/**
+ * Verify a staff JWT. When `expectedUse` is provided, refuses tokens
+ * whose `use` claim doesn't match — that's how `getSessionUser`
+ * rejects a refresh token used as a session cookie and how the
+ * refresh route rejects an access token as a refresh trigger.
+ *
+ * Tokens minted before the `use` claim landed have NO `use` payload
+ * field. We refuse those outright rather than treating them as
+ * `access` — the prior fallback would let still-live legacy refresh
+ * JWTs be smuggled into the session cookie and pass the access
+ * check. Cost: staff logged in before this deploy must log in once.
+ * Bounded by the refresh-token TTL (default 7 days).
+ */
+declare function verifyToken(token: string, secret: string, expectedUse?: NpTokenUse): Promise<NpTokenPayload>;
+/**
+ * True when `err` represents a token-verification failure rather than
+ * an unrelated runtime fault (DB outage, misconfiguration, …). Auth
+ * helpers use this to keep the existing "bad token → 401" behavior
+ * silent while letting infrastructure failures surface as 5xx.
+ *
+ * Covers:
+ *   - `NpAuthError` — `verifyToken` / `verifyMemberToken` rejecting a
+ *     missing or wrong `use` claim, or `verifyCsrf` failing.
+ *   - `jose.errors.JOSEError` — every JWT signature / format /
+ *     expiration failure, including subclasses like `JWTExpired`,
+ *     `JWSSignatureVerificationFailed`, `JWTInvalid`.
+ */
+declare function isTokenVerificationError(err: unknown): boolean;
+
+declare const ARGON2_OPTIONS: Options;
+declare function hashPassword(password: string): Promise<string>;
+declare function verifyPassword(passwordHash: string, password: string): Promise<boolean>;
+
+declare function verifyCsrf(method: string, cookieToken: string | undefined, headerToken: string | undefined): boolean;
+
+/**
+ * Capability-based authorization (#273).
+ *
+ * Replaced the previous parallel `hasRole(user, minRole)` /
+ * `isStaffMod(user)` model. Naming the *behavior* instead of a role
+ * hierarchy means a reviewer spots `can(user, "community.moderate")`
+ * on a comment-mod path regardless of how the role table evolves
+ * later — and the previous trap where a `hasRole(user, "editor")`
+ * check silently dropped moderators is gone by construction.
+ *
+ * Capability vocabulary:
+ *   - `content.publish`    — change publication state on staff-owned
+ *                            content. Editor or admin.
+ *   - `content.author`     — create / edit content. Author, moderator,
+ *                            editor, or admin (moderators get author-
+ *                            level write access in this model so they
+ *                            can leave moderation notes / pinned
+ *                            replies on the content surface).
+ *   - `community.moderate` — comment hide/restore, report triage, ban
+ *                            operations. Admin, editor, or moderator.
+ *   - `admin.manage`       — admin-only surfaces (site CRUD,
+ *                            super-admin-adjacent settings).
+ *
+ * Add new capabilities by extending the union AND the exhaustive
+ * switch below — TypeScript will surface the missing branch.
+ */
+type NpCapability = "content.publish" | "content.author" | "community.moderate" | "admin.manage";
+declare function can(user: NpAuthUser | null | undefined, capability: NpCapability): boolean;
+
+/**
+ * OAuth provider registry — extension point for SSO. A provider plugin
+ * (e.g. `@nexpress/plugin-oauth-github`) registers itself at startup
+ * via `registerOAuthProvider()`; the framework's `/api/auth/oauth/{id}`
+ * routes look it up by id.
+ *
+ * The provider is responsible for:
+ *  - Building the authorize URL (`authorize`).
+ *  - Exchanging the callback code for a normalized profile (`exchange`).
+ *
+ * The framework owns state-cookie signing, identity ↔ user resolution,
+ * session minting, and audit. Providers must NOT touch cookies, the DB,
+ * or response objects directly.
+ */
+/**
+ * Profile returned from a successful `exchange()`. The framework uses
+ * `providerUserId` as the durable identifier — `email` may change at the
+ * provider but `providerUserId` should not. If the provider doesn't
+ * surface `email`, the framework falls back to creating a synthetic
+ * placeholder (`<providerUserId>@<provider>.oauth.local`) so the
+ * `np_users.email NOT NULL UNIQUE` constraint is still satisfied.
+ */
+interface OAuthProfile {
+    /** Stable per-user id from the provider. Required. */
+    providerUserId: string;
+    /** Optional — falls back to synthetic if missing. */
+    email?: string | null;
+    /** Optional — defaults to email local-part on user creation. */
+    name?: string | null;
+    /** Optional — written into `np_user_oauth_identities.metadata`. */
+    avatarUrl?: string | null;
+    /** Optional — full payload the provider wants to remember (e.g. scopes). */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Inputs the provider receives at the two callback boundaries. The
+ * framework picks `redirectUri` from `SITE_URL` (or the request origin
+ * in dev) so the provider doesn't have to know its own deployment URL.
+ */
+interface OAuthAuthorizeParams {
+    state: string;
+    redirectUri: string;
+    /**
+     * PKCE code verifier (32+ char URL-safe random). The framework
+     * generates one for every login and threads it through the state
+     * cookie. Providers that don't support PKCE (e.g. GitHub) ignore it;
+     * providers that require it (e.g. Google) hash it into the
+     * `code_challenge` query param.
+     */
+    codeVerifier: string;
+}
+interface OAuthExchangeParams {
+    code: string;
+    state: string;
+    redirectUri: string;
+    /** Same verifier minted at /start, recovered from the state cookie. */
+    codeVerifier: string;
+}
+interface OAuthProvider {
+    /** Stable id used in route paths and `np_user_oauth_identities.provider`. */
+    id: string;
+    /** Human-readable label for admin UI / login buttons. */
+    label?: string;
+    /**
+     * Returns a fully-qualified URL the framework should redirect the
+     * browser to. Async to allow providers that need to mint per-request
+     * client credentials.
+     */
+    authorize(params: OAuthAuthorizeParams): Promise<string> | string;
+    /**
+     * Validates the callback and returns the normalized profile.
+     * Throwing here aborts the login with `OAUTH_EXCHANGE_FAILED`.
+     */
+    exchange(params: OAuthExchangeParams): Promise<OAuthProfile>;
+}
+/**
+ * Register a provider. Idempotent: re-registering with the same id
+ * overwrites — useful in dev when a plugin's `setup()` runs again on
+ * reload.
+ */
+declare function registerOAuthProvider(provider: OAuthProvider): void;
+declare function getOAuthProvider(id: string): OAuthProvider | undefined;
+declare function listOAuthProviders(): OAuthProvider[];
+/** Reset the registry — tests use this between cases. Not for runtime use. */
+declare function resetOAuthProviders(): void;
+
+/**
+ * Resolves an `OAuthProfile` to a real `np_users` row, in this order:
+ *
+ *  1. Lookup by `(provider, provider_user_id)` — the durable link. This
+ *     is the only path that survives an email change at the provider.
+ *  2. Email-match — if the provider gave us an email and an existing
+ *     user has it, link the OAuth identity to that user. Lets a staff
+ *     member who originally signed up with a password later "sign in
+ *     with Google" and have it just work, without an explicit linking
+ *     UI.
+ *  3. Create — auto-provision a new user with the provider's profile,
+ *     default role `viewer`. The password column is filled with an
+ *     unrecoverable Argon2 hash of a random secret so the column
+ *     constraints are satisfied; the user can later run the
+ *     forgot-password flow to set a real password if they want one.
+ *
+ * Side effects: writes a row into `np_user_oauth_identities` for paths
+ * 2 and 3, updates `metadata` for path 1.
+ */
+interface ResolveOAuthLoginResult {
+    user: ResolvedOAuthUser;
+    /** Tells the caller whether this login created the underlying user. */
+    created: boolean;
+    /** Tells the caller whether this login linked a new identity row. */
+    linked: boolean;
+}
+interface ResolvedOAuthUser {
+    id: string;
+    email: string;
+    name: string;
+    role: NpUserRole;
+    tokenVersion: number;
+}
+interface ResolveOAuthLoginInput {
+    provider: string;
+    profile: OAuthProfile;
+    /** Default role for auto-created users. Defaults to `"viewer"`. */
+    defaultRole?: NpUserRole;
+}
+declare function resolveOAuthLogin(input: ResolveOAuthLoginInput): Promise<ResolveOAuthLoginResult>;
+
+/**
+ * Member-side mirror of `resolveOAuthLogin` (the staff resolver in
+ * `oauth-resolve.ts`). Walks the same three-step ladder:
+ *
+ *   1. Lookup by `(provider, subject)` in `np_member_identities` —
+ *      durable provider link.
+ *   2. Email match — if the profile carries an email, link the
+ *      identity to the existing `np_members` row.
+ *   3. Auto-provision a new member with status=`active`, default
+ *      password = unrecoverable Argon2 of a random secret. The user
+ *      can later run forgot-password to set a real password if they
+ *      want one (or stay SSO-only).
+ *
+ * Members are kept distinct from staff users at every layer
+ * (different table, different cookies, different audience claim on
+ * the JWT). This resolver intentionally never touches `np_users`.
+ */
+interface ResolvedOAuthMember {
+    id: string;
+    email: string;
+    handle: string;
+    displayName: string;
+    status: "active" | "pending" | "suspended" | "deleted";
+    tokenVersion: number;
+}
+interface ResolveMemberOAuthLoginInput {
+    provider: string;
+    profile: OAuthProfile;
+}
+interface ResolveMemberOAuthLoginResult {
+    member: ResolvedOAuthMember;
+    /** True when this login auto-provisioned the underlying member. */
+    created: boolean;
+    /** True when this login linked a new identity row (covers steps 2 + 3). */
+    linked: boolean;
+}
+declare function resolveMemberOAuthLogin(input: ResolveMemberOAuthLoginInput): Promise<ResolveMemberOAuthLoginResult>;
+
+interface OAuthStatePayload {
+    providerId: string;
+    nonce: string;
+    expSeconds: number;
+    codeVerifier: string;
+}
+interface IssuedOAuthState {
+    /** The serialized state token (cookie + redirect query value). */
+    token: string;
+    /** The PKCE verifier — also embedded in the token, surfaced here so
+     *  the route can pass it to `provider.authorize()` without re-parsing. */
+    codeVerifier: string;
+}
+declare function issueOAuthState(providerId: string, secret: string): IssuedOAuthState;
+interface VerifyOAuthStateResult {
+    ok: boolean;
+    payload?: OAuthStatePayload;
+    reason?: "format" | "signature" | "expired";
+}
+/**
+ * Strict verification:
+ *  - Format must be `<payload>.<sig>` with two segments.
+ *  - HMAC must match (constant-time compare).
+ *  - `expSeconds` must be in the future.
+ *  - `providerId` in the payload must match the route's expected provider.
+ *  - `codeVerifier` must be a non-empty string.
+ */
+declare function verifyOAuthState(token: string, expectedProviderId: string, secret: string): VerifyOAuthStateResult;
+
+/**
+ * Adapter that bridges any [arctic](https://arctic.js.org/) provider
+ * (`new GitHub(...)`, `new Google(...)`, `new Apple(...)`, etc.) to
+ * NexPress's `OAuthProvider` interface.
+ *
+ * Why this exists: arctic ships ~25 maintained providers and handles
+ * the OAuth dance — token exchange, PKCE hashing, refresh-token
+ * support — so plugin authors only have to write the **profile fetch**
+ * (the part that varies most by provider). Our framework still owns
+ * state cookies, identity ↔ user resolution, and session minting; this
+ * adapter just lets users skip the boilerplate token POST.
+ *
+ * Usage from a plugin:
+ *
+ *   import { Apple } from "arctic";
+ *   import { fromArctic, registerOAuthProvider } from "@nexpress/core";
+ *
+ *   registerOAuthProvider(fromArctic(
+ *     // Factory: framework calls this each request with the freshly-
+ *     // resolved redirectUri (matters in dev when Next.js may bind a
+ *     // non-default port).
+ *     (redirectUri) => new Apple(clientId, teamId, keyId, privateKey, redirectUri),
+ *     {
+ *       id: "apple",
+ *       scopes: ["name", "email"],
+ *       fetchProfile: async (accessToken, tokens) => {
+ *         // Apple returns the user payload INSIDE the token response
+ *         // (not a separate userinfo endpoint) — pull it from
+ *         // `tokens.idToken()` here and parse the JWT body.
+ *         return { providerUserId: parseAppleSub(tokens.idToken()), email: null };
+ *       },
+ *     },
+ *   ));
+ */
+/**
+ * Minimal slice of arctic's provider classes that the adapter actually
+ * needs. Both `GitHub` (no PKCE) and `Google` (PKCE-required) match
+ * this — the third positional arg is "second positional" for
+ * non-PKCE providers (just unused) and "code verifier" for PKCE ones.
+ *
+ * Declared structurally so we don't drag arctic into the public type
+ * graph of `@nexpress/core`. Plugins that import a real arctic class
+ * pass it directly; the structural match keeps the signature lined up.
+ */
+interface ArcticLikeProvider {
+    createAuthorizationURL(state: string, ...rest: never[]): URL;
+    validateAuthorizationCode(code: string, ...rest: never[]): Promise<ArcticLikeTokens>;
+}
+interface ArcticLikeTokens {
+    accessToken(): string;
+    hasRefreshToken?(): boolean;
+    refreshToken?(): string;
+    idToken?(): string;
+}
+interface FromArcticOptions {
+    /** Provider id used in route paths and `np_user_oauth_identities.provider`. */
+    id: string;
+    /** Human label for admin UI / login buttons. */
+    label?: string;
+    /** Scopes passed to `createAuthorizationURL`. Most providers default
+     *  to nothing useful — set this. */
+    scopes?: string[];
+    /**
+     * Whether the underlying arctic provider expects a PKCE code verifier
+     * as the second arg to `createAuthorizationURL` and
+     * `validateAuthorizationCode`. Default `true` (Google, Apple, etc.).
+     * Set `false` for non-PKCE providers like GitHub.
+     */
+    pkce?: boolean;
+    /**
+     * Turns an access token (and the full token response, useful for
+     * providers like Apple that return the profile in the token) into the
+     * normalized `OAuthProfile` consumed by `resolveOAuthLogin`.
+     *
+     * Throwing aborts the login with `oauth_error=exchange_failed`.
+     */
+    fetchProfile: (accessToken: string, tokens: ArcticLikeTokens) => Promise<OAuthProfile>;
+}
+/**
+ * Wraps an arctic provider into the framework's `OAuthProvider`
+ * shape. The framework calls `authorize` and `exchange`; this adapter
+ * builds a fresh arctic instance per request via `factory(redirectUri)`
+ * so the redirect URI always matches what the framework computed for
+ * THIS request — critical in dev where Next.js may fall back to a
+ * non-3000 port and a setup-time-frozen redirectUri would diverge.
+ *
+ * Arctic provider classes are cheap to construct (just hold the three
+ * credential strings), so the per-request factory call has no
+ * meaningful cost.
+ */
+declare function fromArctic(factory: (redirectUri: string) => ArcticLikeProvider, opts: FromArcticOptions): OAuthProvider;
+
+/**
+ * Loose Drizzle handle type — every staff-auth caller passes
+ * the same NodePgDatabase, but TS over-narrows when the
+ * generated schema record is folded in. Using
+ * `Record<string, unknown>` keeps the helper portable across
+ * schema generations without surfacing as `any`.
+ */
+type SessionDb = NodePgDatabase<Record<string, unknown>>;
+declare function sha256(input: string): Promise<string>;
+/**
+ * Verify a staff JWT and resolve the active user.
+ *
+ * `expectedUse` defaults to `"access"` because every caller of this
+ * helper outside the rotation endpoint reads `np-session` (server
+ * components, route handlers, the bootstrap layout). Defaulting
+ * means a fresh route or RSC page can't accidentally tolerate a
+ * refresh JWT in the session cookie just by forgetting the
+ * argument. The rotation route explicitly passes `"refresh"` for
+ * its `np-refresh` read.
+ *
+ * Tokens missing the `use` claim throw via `verifyToken`; we let
+ * that propagate so a `NpAuthError` surfaces as 401 at the API
+ * layer.
+ */
+declare function verifyTokenFull(token: string, secret: string, db: SessionDb, expectedUse?: NpTokenUse): Promise<NpAuthUser | null>;
+declare function invalidateAllSessions(userId: string, db: SessionDb): Promise<void>;
+
+/**
+ * Admin-side helpers for listing and revoking OAuth identity links.
+ * Both staff (`np_user_oauth_identities`) and member
+ * (`np_member_identities`) tables use the same shape: one row per
+ * (account, provider) pair, holding the durable provider subject
+ * plus arbitrary metadata. These helpers are the source of truth for
+ * `/api/admin/users/[id]/identities` and the member equivalent.
+ *
+ * Revoking does not invalidate sessions — the user / member can
+ * re-link by signing in via OAuth again, which creates a fresh
+ * identity row through the resolver. Revocation is intentionally
+ * reversible because the durable link is the only thing dropped;
+ * the underlying account remains.
+ */
+interface NpUserIdentityRow {
+    id: string;
+    userId: string;
+    provider: string;
+    providerUserId: string;
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+interface NpMemberIdentityRow {
+    id: string;
+    memberId: string;
+    provider: string;
+    subject: string;
+    email: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+declare function listUserIdentities(userId: string): Promise<NpUserIdentityRow[]>;
+declare function listMemberIdentities(memberId: string): Promise<NpMemberIdentityRow[]>;
+interface RevokeIdentityInput {
+    /** Staff user id whose identity is being revoked (`actorKind: "staff"`). */
+    staffUserId: string;
+}
+declare function revokeUserIdentity(userId: string, identityId: string, actor: RevokeIdentityInput): Promise<void>;
+declare function revokeMemberIdentity(memberId: string, identityId: string, actor: RevokeIdentityInput): Promise<void>;
+
+type NpPasswordResetPurpose = "invite" | "reset";
+interface NpIssuedResetToken {
+    /** The raw token — deliver to the user, never persist. */
+    token: string;
+    /** Matches `np_users.password_reset_expires_at`. */
+    expiresAt: Date;
+    purpose: NpPasswordResetPurpose;
+}
+interface NpCreateResetTokenOptions {
+    userId: string;
+    purpose: NpPasswordResetPurpose;
+    ttlMs: number;
+}
+/**
+ * Issues a new password reset token for `userId`. Stores the **hash** of the
+ * token in the `np_users` row alongside the expiry and purpose, then returns
+ * the raw token for the caller to deliver (email/link).
+ *
+ * Any previously-outstanding reset token for the user is replaced.
+ */
+declare function createPasswordResetToken(db: NodePgDatabase<Record<string, unknown>>, options: NpCreateResetTokenOptions): Promise<NpIssuedResetToken>;
+interface NpResetRequestResult {
+    userId: string | null;
+    name: string | null;
+    email: string | null;
+    issued: NpIssuedResetToken | null;
+}
+/**
+ * Handles the "forgot password" flow. If the email matches a user, issues a
+ * reset token and returns their name so the mailer can personalise the email.
+ * If not, silently returns nulls so callers can respond with a constant
+ * message and avoid email enumeration.
+ */
+declare function requestPasswordReset(db: NodePgDatabase<Record<string, unknown>>, email: string, ttlMs: number): Promise<NpResetRequestResult>;
+interface NpConsumeResetTokenOptions {
+    token: string;
+    newPassword: string;
+}
+interface NpConsumeResetTokenResult {
+    userId: string;
+    email: string;
+    purpose: NpPasswordResetPurpose;
+}
+/**
+ * Verifies a password reset token and atomically:
+ * - sets the new password hash
+ * - bumps `tokenVersion` and deletes all sessions (force logout everywhere)
+ * - clears the reset columns on the user row
+ *
+ * Throws `NpValidationError` when the token is unknown, expired, or the
+ * password is too short. Uses a single DB transaction for atomicity.
+ */
+declare function consumePasswordResetToken(db: NodePgDatabase<Record<string, unknown>>, options: NpConsumeResetTokenOptions): Promise<NpConsumeResetTokenResult>;
+
+/**
+ * Member-side JWT helpers. Mirrors `signToken` / `verifyToken` for
+ * staff but adds a fixed `aud: "member"` claim so a forged JWT signed
+ * for a staff user can't be replayed against member-only routes (and
+ * vice-versa).
+ *
+ * The signing secret is the same `NP_SECRET`; rotating it invalidates
+ * both staff and member sessions, which is the desired behavior.
+ *
+ * Every token gets a random `jti` so two tokens minted within the
+ * same second for the same member produce DIFFERENT JWT strings —
+ * needed for refresh-token rotation: without it, the rotated token
+ * hash would collide with the prior token hash and revocation by
+ * tokenHash would still resolve the rotated row.
+ *
+ * `use: "access" | "refresh"` separates the two token purposes. A
+ * refresh JWT cannot be presented as the `np-mb-session` cookie and
+ * a session JWT cannot drive the rotation endpoint — without this
+ * separation a leaked refresh token effectively became a long-lived
+ * bearer access token because both kinds were stored as fungible
+ * rows in `np_member_sessions` with no row-level kind column.
+ */
+type NpMemberTokenUse = "access" | "refresh";
+interface NpMemberTokenPayload {
+    sub: string;
+    aud: "member";
+    ver: number;
+    /** Required. `verifyMemberToken` refuses tokens missing this claim
+     *  so legacy refresh JWTs from before #92 cannot be smuggled into
+     *  the session cookie path (#91 reopen). */
+    use: NpMemberTokenUse;
+    /** Optional only for the deploy window; new tokens always carry
+     *  one. */
+    jti?: string;
+    iat: number;
+    exp: number;
+}
+declare function signMemberToken(member: {
+    id: string;
+    tokenVersion: number;
+}, secret: string, expirationSeconds?: number, tokenUse?: NpMemberTokenUse): Promise<string>;
+/**
+ * Verify a member JWT and return the parsed payload. When
+ * `expectedUse` is provided, refuses tokens whose `use` claim doesn't
+ * match — that's how `getSessionMember` rejects a refresh token used
+ * as a session cookie and how the refresh route rejects an access
+ * token as a refresh trigger.
+ *
+ * Tokens minted before the `use` claim landed have NO `use` payload
+ * field. We refuse those outright rather than treating them as
+ * `access` — the prior fallback let still-live legacy refresh JWTs
+ * (already persisted in `np_member_sessions` per #45's fix) be
+ * smuggled into the session cookie and pass the access check (#91
+ * reopen). The cost: members logged in before this deploy must log
+ * in once. That's bounded by the access-token TTL (default 2h);
+ * legacy session rows that don't match a new login age out via
+ * `expiresAt` within 7 days regardless.
+ */
+declare function verifyMemberToken(token: string, secret: string, expectedUse?: NpMemberTokenUse): Promise<NpMemberTokenPayload>;
+
+/**
+ * Member-side session lookups, mirroring the staff helpers in session.ts
+ * but for `np_members` / `np_member_sessions`. The sha256 helper is
+ * reused (sessions store hashed tokens regardless of the principal kind).
+ */
+interface NpMemberAuthRow {
+    id: string;
+    email: string;
+    handle: string;
+    displayName: string;
+    status: "active" | "pending" | "suspended" | "deleted";
+    tokenVersion: number;
+}
+/**
+ * Resolve a member from a verified JWT payload AND the raw access
+ * token. We hash the token and require a live row in
+ * `np_member_sessions` — without that row check, deleting a session in
+ * `/api/members/logout` had no effect and a stolen token kept working
+ * until JWT expiry. (#45)
+ *
+ * Backward-compat: when no `accessToken` is passed (legacy callers in
+ * tests / older routes), we fall back to the previous tokenVersion
+ * check only. New paths should always pass the token.
+ */
+declare function getMemberFromTokenPayload(db: NodePgDatabase<Record<string, unknown>>, payload: {
+    sub: string;
+    ver: number;
+}, accessToken?: string): Promise<NpMemberAuthRow | null>;
+/**
+ * Bumps a member's tokenVersion + drops every session row, force-logging
+ * them out everywhere. Call inside the same transaction as a password
+ * change / soft-delete so a leaked old JWT can't outlive the change.
+ */
+declare function invalidateAllMemberSessions(db: NodePgDatabase<Record<string, unknown>>, memberId: string): Promise<void>;
+
+interface NpIssuedMemberToken {
+    /** The raw token to ship to the user. Never persist. */
+    token: string;
+    expiresAt: Date;
+}
+declare function createMemberEmailVerifyToken(db: NodePgDatabase<Record<string, unknown>>, memberId: string, ttlMs: number): Promise<NpIssuedMemberToken>;
+interface NpConsumeMemberEmailVerifyResult {
+    memberId: string;
+    email: string;
+    handle: string;
+    displayName: string;
+}
+declare function consumeMemberEmailVerifyToken(db: NodePgDatabase<Record<string, unknown>>, token: string): Promise<NpConsumeMemberEmailVerifyResult>;
+interface NpMemberResetRequestResult {
+    memberId: string | null;
+    displayName: string | null;
+    email: string | null;
+    issued: NpIssuedMemberToken | null;
+}
+declare function requestMemberPasswordReset(db: NodePgDatabase<Record<string, unknown>>, email: string, ttlMs: number): Promise<NpMemberResetRequestResult>;
+interface NpConsumeMemberResetResult {
+    memberId: string;
+    email: string;
+}
+declare function consumeMemberPasswordReset(db: NodePgDatabase<Record<string, unknown>>, token: string, newPassword: string): Promise<NpConsumeMemberResetResult>;
+
+export { ARGON2_OPTIONS, type ArcticLikeProvider, type ArcticLikeTokens, type FromArcticOptions, type IssuedOAuthState, type NpCapability, type NpConsumeMemberEmailVerifyResult, type NpConsumeMemberResetResult, type NpConsumeResetTokenOptions, type NpConsumeResetTokenResult, type NpCreateResetTokenOptions, type NpIssuedMemberToken, type NpIssuedResetToken, type NpMemberAuthRow, type NpMemberIdentityRow, type NpMemberResetRequestResult, type NpMemberTokenPayload, type NpPasswordResetPurpose, type NpResetRequestResult, type NpTokenPayload, type NpUserIdentityRow, type OAuthAuthorizeParams, type OAuthExchangeParams, type OAuthProfile, type OAuthProvider, type OAuthStatePayload, type ResolveMemberOAuthLoginInput, type ResolveMemberOAuthLoginResult, type ResolveOAuthLoginInput, type ResolveOAuthLoginResult, type ResolvedOAuthMember, type ResolvedOAuthUser, type VerifyOAuthStateResult, authenticated, can, consumeMemberEmailVerifyToken, consumeMemberPasswordReset, consumePasswordResetToken, createMemberEmailVerifyToken, createPasswordResetToken, fromArctic, getMemberFromTokenPayload, getOAuthProvider, hashPassword, invalidateAllMemberSessions, invalidateAllSessions, isAdmin, isEditorOrAbove, isOwnerOrAdmin, isTokenVerificationError, issueOAuthState, listMemberIdentities, listOAuthProviders, listUserIdentities, registerOAuthProvider, requestMemberPasswordReset, requestPasswordReset, resetOAuthProviders, resolveMemberOAuthLogin, resolveOAuthLogin, revokeMemberIdentity, revokeUserIdentity, sha256, signMemberToken, signToken, verifyCsrf, verifyMemberToken, verifyOAuthState, verifyPassword, verifyToken, verifyTokenFull };