@stacksjs/auth 0.70.88 → 0.70.91

package/dist/team.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Pure resolver — no I/O — that decides which team is "active" for a user
+ * given their memberships and an optional switch preference. Reusable across
+ * apps: it encodes the whole workspace-switching precedence in one place.
+ *
+ * - Honors `activeTeamId` only when the user may access it: a member always
+ *   may; a privileged operator may access any team when `allowAnyTeam` is set
+ *   (the app decides who is privileged — e.g. a super-admin flag).
+ * - Otherwise falls back to the highest-priority membership (owner > admin >
+ *   anything else), matching what dashboard pages have always shown, so the
+ *   "current team" never differs between a rendered form and the action it
+ *   posts to.
+ */
+export declare function selectActiveTeam(opts: {
+  memberships: Array<{ team_id: number | string, role?: string | null }>
+  activeTeamId?: number | null
+  allowAnyTeam?: boolean
+  rolePriority?: Record<string, number>
+}): { teamId: number | null, role: string | null };
+/** Read the active-team switch preference from a request's cookie. */
+export declare function getActiveTeamPreference(request: TeamAuthRequest): number | null;
+/**
+ * Build the `Set-Cookie` that pins the active team (workspace switcher). A
+ * year-long HttpOnly cookie: only the server needs it (SSR reads it, the
+ * switch action writes it), and it carries no privilege of its own.
+ */
+export declare function buildActiveTeamCookie(teamId: number, opts?: { maxAgeSeconds?: number, secure?: boolean }): string;
+/** Clear the active-team cookie {@link buildActiveTeamCookie} sets. */
+export declare function clearActiveTeamCookie(): string;
+/**
+ * Resolve the requesting user's active team membership (team id + role)
+ * from their auth credential. Driver-aware: reads config/auth.ts's
+ * configured guard driver rather than hardcoding a validation scheme.
+ *
+ * Dashboard forms are plain HTML POSTs (no client JS, no Authorization
+ * header) — the browser only ever sends the auth cookie set on login,
+ * so that's checked for the 'token' driver alongside a bearer-header
+ * fallback for JS/API callers.
+ *
+ * Owner membership wins over admin, which wins over any other active
+ * membership, when a user belongs to more than one team — the same
+ * precedence server-rendered dashboard pages use, so a user never sees
+ * a different "current team" between the page that rendered a form and
+ * the action that form posts to.
+ *
+ * Returns `null` when unauthenticated or without an active team
+ * membership — callers must treat that as "reject the request," not
+ * "fall back to a default team."
+ */
+export declare function resolveAuthenticatedMembership(request: TeamAuthRequest): Promise<TeamMembershipResult | null>;
+/**
+ * Full team context for a server-rendered dashboard: the authenticated user,
+ * the resolved active team (honoring the workspace switcher), and the list of
+ * teams the user can switch between. One call replaces the per-page auth+team
+ * boilerplate every dashboard view used to copy, and centralizes the
+ * switch-aware scoping so pages and the actions they post to never disagree.
+ *
+ * `opts.allowAnyTeam(user)` lets an app grant an operator (e.g. a super-admin)
+ * access to every team — they can switch to, and see, teams they aren't a
+ * member of. The full user row is returned so the app can read its own
+ * columns (like a super-admin flag) without a second query.
+ */
+export declare function resolveTeamContext(request: TeamAuthRequest, opts?: { allowAnyTeam?: (user: any) => boolean }): Promise<TeamContext>;
+/**
+ * Team id only — the common case for actions that just need to scope a
+ * write to the requester's team. See {@link resolveAuthenticatedMembership}
+ * when the caller also needs the role (e.g. owner/admin-only settings).
+ */
+export declare function resolveAuthenticatedTeamId(request: TeamAuthRequest): Promise<number | null>;
+/**
+ * The authenticated USER (not team) from a request's real auth
+ * credential — bearer header first, then the login cookie, driver-aware
+ * like {@link resolveAuthenticatedMembership} (which builds on this).
+ * For dashboard form actions that operate on the requester themselves
+ * (security settings, profile) rather than on team-scoped rows: plain
+ * HTML POSTs carry no Authorization header, so `request.user()` (stamped
+ * by the auth middleware from a bearer/session) is undefined there and
+ * the login cookie is the only credential available.
+ */
+export declare function resolveAuthenticatedUser(request: TeamAuthRequest): Promise<{ id: number, email?: string } | undefined>;
+/**
+ * Name of the cookie that remembers which team the user last switched the
+ * dashboard to (a workspace switcher). It is NOT a security credential: the
+ * server re-validates membership against `selectActiveTeam` on every request,
+ * so a tampered value can only ever resolve to a team the user already
+ * belongs to (or, for operators, any team when `allowAnyTeam` is set).
+ */
+export declare const ACTIVE_TEAM_COOKIE: 'active_team';
+/**
+ * Team resolution from a request's real auth credential (bearer token or
+ * session cookie) — never from a client-supplied form field. Extracted
+ * from app-land (stacksjs/status config/auth-team.ts) because every app
+ * with team-scoped dashboard forms needs exactly this, and `config/` is
+ * for autoloaded config files, not shared helpers.
+ *
+ * Structural request type on purpose: callers pass whatever request
+ * object their action received. Partial objects (tests, non-HTTP
+ * callers) resolve to "unauthenticated" rather than crashing.
+ */
+export declare interface TeamAuthRequest {
+  bearerToken?: () => string | null | undefined
+  cookies?: { get: (name: string) => string | null | undefined }
+}
+export declare interface TeamMembershipResult {
+  teamId: number
+  role: string
+}
+/** A team the authenticated user may switch the dashboard to. */
+export declare interface SwitchableTeam {
+  id: number
+  name: string
+  role: string
+}
+/** Full dashboard team context — see {@link resolveTeamContext}. */
+export declare interface TeamContext {
+  user: any | null
+  teamId: number | null
+  role: string | null
+  teams: SwitchableTeam[]
+  activeTeamId: number | null
+}

package/dist/team.js

@@ -0,0 +1,88 @@
+import { config } from "@stacksjs/config";
+import { db } from "@stacksjs/database";
+import { Auth } from "./authentication";
+import { sessionUser } from "./session-auth";
+export const ACTIVE_TEAM_COOKIE = "active_team";
+export function selectActiveTeam(opts) {
+  const priority = opts.rolePriority ?? { owner: 0, admin: 1 }, sorted = [...opts.memberships ?? []].sort((a, b) => (priority[a.role ?? ""] ?? 2) - (priority[b.role ?? ""] ?? 2)), active = opts.activeTeamId == null ? null : Number(opts.activeTeamId);
+  if (active != null && Number.isFinite(active)) {
+    const member = sorted.find((x) => Number(x.team_id) === active);
+    if (member)
+      return { teamId: active, role: member.role ?? null };
+    if (opts.allowAnyTeam)
+      return { teamId: active, role: "admin" };
+  }
+  const first = sorted[0];
+  return first ? { teamId: Number(first.team_id), role: first.role ?? null } : { teamId: null, role: null };
+}
+export function getActiveTeamPreference(request) {
+  const raw = request.cookies?.get(ACTIVE_TEAM_COOKIE);
+  if (!raw)
+    return null;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+export function buildActiveTeamCookie(teamId, opts = {}) {
+  const maxAge = Math.max(0, Math.floor(opts.maxAgeSeconds ?? 31536000)), parts = [`${ACTIVE_TEAM_COOKIE}=${encodeURIComponent(String(teamId))}`, "Path=/", "HttpOnly", "SameSite=Lax", `Max-Age=${maxAge}`];
+  if (opts.secure)
+    parts.push("Secure");
+  return parts.join("; ");
+}
+export function clearActiveTeamCookie() {
+  return `${ACTIVE_TEAM_COOKIE}=; Path=/; HttpOnly; SameSite=Lax; Max-Age=0`;
+}
+export async function resolveAuthenticatedMembership(request) {
+  const user = await resolveAuthenticatedUser(request);
+  if (!user?.id)
+    return null;
+  const memberships = await db.selectFrom("team_members").where("user_id", "=", user.id).where("status", "=", "active").select(["team_id", "role"]).execute();
+  if (memberships.length === 0)
+    return null;
+  const picked = selectActiveTeam({
+    memberships: memberships.map((m) => ({
+      team_id: Number(m.team_id),
+      role: m.role == null ? null : String(m.role)
+    })),
+    activeTeamId: getActiveTeamPreference(request)
+  });
+  return picked.teamId != null ? { teamId: picked.teamId, role: picked.role ?? "" } : null;
+}
+export async function resolveTeamContext(request, opts = {}) {
+  const empty = { user: null, teamId: null, role: null, teams: [], activeTeamId: null }, guardName = config.auth?.default || "api", user = (config.auth?.guards?.[guardName]?.driver || "token") === "session" ? await resolveSessionUser(request) : await resolveTokenUser(request);
+  if (!user?.id)
+    return empty;
+  const memberships = await db.selectFrom("team_members").where("user_id", "=", user.id).where("status", "=", "active").select(["team_id", "role"]).execute(), allowAny = opts.allowAnyTeam ? !!opts.allowAnyTeam(user) : !1, activeTeamId = getActiveTeamPreference(request), picked = selectActiveTeam({
+    memberships: memberships.map((m) => ({ team_id: Number(m.team_id), role: String(m.role) })),
+    activeTeamId,
+    allowAnyTeam: allowAny
+  }), roleByTeam = new Map(memberships.map((m) => [Number(m.team_id), String(m.role)]));
+  let teamRows = [];
+  if (allowAny)
+    teamRows = await db.selectFrom("teams").select(["id", "name"]).execute();
+  else {
+    const ids = [...roleByTeam.keys()];
+    teamRows = ids.length ? await db.selectFrom("teams").whereIn("id", ids).select(["id", "name"]).execute() : [];
+  }
+  const teams = teamRows.map((t) => ({ id: Number(t.id), name: String(t.name), role: roleByTeam.get(Number(t.id)) || "viewer" })).sort((a, b) => a.name.localeCompare(b.name));
+  return { user, teamId: picked.teamId, role: picked.role, teams, activeTeamId };
+}
+export async function resolveAuthenticatedTeamId(request) {
+  const membership = await resolveAuthenticatedMembership(request);
+  return membership ? membership.teamId : null;
+}
+export async function resolveAuthenticatedUser(request) {
+  const guardName = config.auth?.default || "api", user = ((config.auth?.guards?.[guardName] || { driver: "token" }).driver || "token") === "session" ? await resolveSessionUser(request) : await resolveTokenUser(request);
+  return user?.id ? user : void 0;
+}
+async function resolveSessionUser(request) {
+  const sessionId = request.cookies?.get("session_id");
+  if (!sessionId)
+    return;
+  return sessionUser(sessionId);
+}
+async function resolveTokenUser(request) {
+  const cookieName = config.auth?.defaultTokenName || "auth-token", bearer = (typeof request.bearerToken === "function" ? request.bearerToken() : void 0) ?? request.cookies?.get(cookieName);
+  if (!bearer)
+    return;
+  return Auth.getUserFromToken(bearer);
+}

package/dist/token.d.ts

@@ -0,0 +1,16 @@
+export type { AuthToken } from '@stacksjs/types';
+/**
+ * `TokenManager` used to expose `createAccessToken` / `validateToken` /
+ * `rotateToken` / `revokeToken` static methods that hardcoded a 30-day
+ * `expires_at`, bypassed `config.auth.tokenExpiry`, and compared raw
+ * tokens against DB-stored hashes (i.e. broken). They had no callers —
+ * the real path lives on `Auth` (see authentication.ts) and respects
+ * the configured 1-hour expiry plus the refresh-token rotation
+ * landed for #1839. Removed entirely so the trap can't fire.
+ *
+ * `generateJWT` is the one piece worth keeping — `Auth.createTokenForUser`
+ * and `Auth.rotateToken` both use it to mint the JWT body.
+ */
+export declare class TokenManager {
+  static generateJWT(userId: number, expiresInSeconds?: number): string;
+}

package/dist/token.js

@@ -0,0 +1,21 @@
+import { Buffer } from "node:buffer";
+import { createHmac, randomBytes } from "node:crypto";
+import process from "node:process";
+
+export class TokenManager {
+  static generateJWT(userId, expiresInSeconds = 3600) {
+    const appKey = process.env.APP_KEY;
+    if (!appKey)
+      throw Error("APP_KEY is not set. JWT tokens cannot be generated without a secure application key.");
+    const header = {
+      alg: "HS256",
+      typ: "JWT"
+    }, nowSeconds = Math.floor(Date.now() / 1000), payload = {
+      sub: userId,
+      iat: nowSeconds,
+      exp: nowSeconds + expiresInSeconds,
+      jti: randomBytes(16).toString("hex")
+    }, encodedHeader = Buffer.from(JSON.stringify(header)).toString("base64url"), encodedPayload = Buffer.from(JSON.stringify(payload)).toString("base64url"), signature = createHmac("sha256", appKey).update(`${encodedHeader}.${encodedPayload}`).digest("base64url");
+    return `${encodedHeader}.${encodedPayload}.${signature}`;
+  }
+}

package/dist/tokens.d.ts

@@ -0,0 +1,284 @@
+import type { AccessToken, CreateClientOptions, CreateClientResult, DatabaseDriver, OAuthClient, PersonalAccessTokenResult, RefreshTokenResult, TokenScopes } from '@stacksjs/types';
+/**
+ * Read `users.password_changed_at` for a user.
+ *
+ * Binds a token's validity to the account's credential state: a token
+ * issued before the user last changed their password is no longer
+ * trusted, regardless of its own `revoked`/`expires_at` flags. This is
+ * the durable, use-time backstop behind the post-reset revocation sweep
+ * (#1947) — even a freshly minted pair that the sweep never saw is
+ * rejected on first use.
+ *
+ * Returns `null` on ANY error (missing column / missing table) so a
+ * not-yet-migrated database degrades to legacy-allow rather than locking
+ * everyone out. Accepts an optional query runner so the refresh exchange
+ * can read the stamp inside its own transaction.
+ */
+export declare function getPasswordChangedAt(userId: unknown, q?: { unsafe: (sql: string, params?: any[]) => any }): Promise<Date | null>;
+/**
+ * True when a credential issued at `createdAt` predates the user's last
+ * password change (`changedAt`) and must therefore be rejected.
+ *
+ * Legacy-allow semantics:
+ * - `changedAt` null (no stamp / un-migrated) => never reject.
+ * - `createdAt` missing/unparseable => never reject.
+ *
+ * Strict `<` so a token minted in the SAME second as (or after) the
+ * reset — e.g. the victim's immediate post-reset login — is NOT bricked
+ * by CURRENT_TIMESTAMP's one-second granularity.
+ */
+export declare function isIssuedBeforePasswordChange(createdAt: unknown, changedAt: Date | null): boolean;
+/**
+ * Get all access tokens for a user
+ *
+ * @example
+ * import { tokens } from '@stacksjs/auth'
+ * const userTokens = await tokens(user.id)
+ */
+export declare function tokens(userId: number): Promise<AccessToken[]>;
+/**
+ * Get a specific token by its plain text value
+ * Uses hash comparison for security
+ *
+ * @example
+ * import { findToken } from '@stacksjs/auth'
+ * const token = await findToken('abc123...')
+ */
+export declare function findToken(plainTextToken: string): Promise<AccessToken | null>;
+/**
+ * Get the current access token from the request context
+ *
+ * @example
+ * import { currentAccessToken } from '@stacksjs/auth'
+ * const token = await currentAccessToken()
+ */
+export declare function currentAccessToken(): Promise<AccessToken | null>;
+/**
+ * Check if the current token has a given scope/ability
+ *
+ * @example
+ * import { tokenCan } from '@stacksjs/auth'
+ * if (await tokenCan('posts:create')) {
+ *   // user can create posts
+ * }
+ */
+export declare function tokenCan(scope: string): Promise<boolean>;
+/**
+ * Check if the current token does NOT have a given scope/ability
+ *
+ * @example
+ * import { tokenCant } from '@stacksjs/auth'
+ * if (await tokenCant('admin')) {
+ *   throw new Error('Admin access required')
+ * }
+ */
+export declare function tokenCant(scope: string): Promise<boolean>;
+/**
+ * Check if token has ALL of the given scopes
+ *
+ * @example
+ * import { tokenCanAll } from '@stacksjs/auth'
+ * if (await tokenCanAll(['posts:read', 'posts:write'])) {
+ *   // user has both scopes
+ * }
+ */
+export declare function tokenCanAll(scopes: string[]): Promise<boolean>;
+/**
+ * Check if token has ANY of the given scopes
+ *
+ * @example
+ * import { tokenCanAny } from '@stacksjs/auth'
+ * if (await tokenCanAny(['admin', 'moderator'])) {
+ *   // user has at least one of the scopes
+ * }
+ */
+export declare function tokenCanAny(scopes: string[]): Promise<boolean>;
+/**
+ * Get all scopes/abilities for the current token
+ *
+ * @example
+ * import { tokenAbilities } from '@stacksjs/auth'
+ * const abilities = await tokenAbilities()
+ * // ['read', 'write', 'posts:create']
+ */
+export declare function tokenAbilities(): Promise<string[]>;
+/**
+ * Create a new personal access token for a user
+ * Tokens are hashed before storage for security
+ *
+ * @param userId - The user ID to create the token for
+ * @param name - A name/description for the token
+ * @param scopes - Array of scopes/abilities for the token
+ * @param options - Additional options
+ * @param options.expiresInMinutes - Token expiry in minutes (default: 60)
+ * @param options.withRefreshToken - Whether to create a refresh token (default: true)
+ * @param options.refreshExpiresInDays - Refresh token expiry in days (default: 30)
+ *
+ * @example
+ * import { createToken } from '@stacksjs/auth'
+ * const result = await createToken(user.id, 'My API Token', ['read', 'write'])
+ * console.log(result.plainTextToken) // Save this - it won't be shown again!
+ * console.log(result.refreshToken)   // Use this to get new access tokens
+ */
+export declare function createToken(userId: number, name?: string, scopes?: string[], options?: {
+    expiresInMinutes?: number
+    withRefreshToken?: boolean
+    refreshExpiresInDays?: number
+  }): Promise<PersonalAccessTokenResult>;
+/**
+ * Exchange a refresh token for a new access token
+ *
+ * @param refreshTokenPlain - The plain text refresh token
+ * @param options - Additional options
+ * @param options.expiresInMinutes - New access token expiry in minutes (default: 60)
+ * @param options.refreshExpiresInDays - New refresh token expiry in days (default: 30)
+ *
+ * @example
+ * import { refreshToken } from '@stacksjs/auth'
+ * const result = await refreshToken('your-refresh-token')
+ * // Use result.plainTextToken as new access token
+ * // Use result.refreshToken as new refresh token (old one is revoked)
+ */
+export declare function refreshToken(refreshTokenPlain: string, options?: {
+    expiresInMinutes?: number
+    refreshExpiresInDays?: number
+  }): Promise<RefreshTokenResult>;
+/**
+ * Validate a refresh token without exchanging it
+ *
+ * @example
+ * import { validateRefreshToken } from '@stacksjs/auth'
+ * const isValid = await validateRefreshToken('your-refresh-token')
+ */
+export declare function validateRefreshToken(refreshTokenPlain: string): Promise<boolean>;
+/**
+ * Revoke a specific refresh token
+ *
+ * @example
+ * import { revokeRefreshToken } from '@stacksjs/auth'
+ * await revokeRefreshToken('your-refresh-token')
+ */
+export declare function revokeRefreshToken(refreshTokenPlain: string): Promise<void>;
+/**
+ * Revoke all refresh tokens for a user
+ *
+ * @example
+ * import { revokeAllRefreshTokens } from '@stacksjs/auth'
+ * await revokeAllRefreshTokens(user.id)
+ */
+export declare function revokeAllRefreshTokens(userId: number): Promise<void>;
+/**
+ * Delete expired refresh tokens (cleanup)
+ *
+ * @example
+ * import { deleteExpiredRefreshTokens } from '@stacksjs/auth'
+ * const count = await deleteExpiredRefreshTokens()
+ */
+export declare function deleteExpiredRefreshTokens(): Promise<number>;
+/**
+ * Delete revoked refresh tokens older than specified days
+ *
+ * @example
+ * import { deleteRevokedRefreshTokens } from '@stacksjs/auth'
+ * const count = await deleteRevokedRefreshTokens(7)
+ */
+export declare function deleteRevokedRefreshTokens(daysOld?: number): Promise<number>;
+/**
+ * Revoke a specific access token
+ *
+ * @example
+ * import { revokeToken } from '@stacksjs/auth'
+ * await revokeToken('abc123...')
+ */
+export declare function revokeToken(plainTextToken: string): Promise<void>;
+/**
+ * Revoke a token by its ID
+ *
+ * @example
+ * import { revokeTokenById } from '@stacksjs/auth'
+ * await revokeTokenById(123)
+ */
+export declare function revokeTokenById(tokenId: number): Promise<void>;
+/**
+ * Revoke all tokens for a user
+ *
+ * @example
+ * import { revokeAllTokens } from '@stacksjs/auth'
+ * await revokeAllTokens(user.id)
+ */
+export declare function revokeAllTokens(userId: number): Promise<void>;
+/**
+ * Revoke all tokens except the current one
+ *
+ * @example
+ * import { revokeOtherTokens } from '@stacksjs/auth'
+ * await revokeOtherTokens(user.id)
+ */
+export declare function revokeOtherTokens(userId: number): Promise<void>;
+/**
+ * Delete expired tokens (cleanup)
+ *
+ * @example
+ * import { deleteExpiredTokens } from '@stacksjs/auth'
+ * const count = await deleteExpiredTokens()
+ */
+export declare function deleteExpiredTokens(): Promise<number>;
+/**
+ * Delete revoked tokens older than specified days
+ *
+ * @example
+ * import { deleteRevokedTokens } from '@stacksjs/auth'
+ * const count = await deleteRevokedTokens(30) // older than 30 days
+ */
+export declare function deleteRevokedTokens(daysOld?: number): Promise<number>;
+/**
+ * Get all OAuth clients for a user
+ *
+ * @example
+ * import { clients } from '@stacksjs/auth'
+ * const userClients = await clients(user.id)
+ */
+export declare function clients(userId: number): Promise<OAuthClient[]>;
+/**
+ * Get a specific OAuth client by ID
+ *
+ * @example
+ * import { findClient } from '@stacksjs/auth'
+ * const client = await findClient(1)
+ */
+export declare function findClient(clientId: number): Promise<OAuthClient | null>;
+/**
+ * Create a new OAuth client
+ *
+ * @example
+ * import { createClient } from '@stacksjs/auth'
+ * const client = await createClient({
+ *   name: 'My App',
+ *   redirect: 'https://myapp.com/callback'
+ * })
+ */
+export declare function createClient(options: CreateClientOptions): Promise<CreateClientResult>;
+/**
+ * Revoke an OAuth client
+ *
+ * @example
+ * import { revokeClient } from '@stacksjs/auth'
+ * await revokeClient(1)
+ */
+export declare function revokeClient(clientId: number): Promise<void>;
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+export declare function parseScopes(scopes: string | string[] | null | undefined): TokenScopes;
+/** Current database driver */
+declare const dbDriver: DatabaseDriver;
+/** Cross-database SQL helpers */
+declare const sql: unknown;
+/**
+ * Alias for currentAccessToken
+ *
+ * @example
+ * import { token } from '@stacksjs/auth'
+ * const t = await token()
+ */
+export declare const token: unknown;