nextly 0.0.1 → 0.0.2-alpha.0

package/dist/auth/index.d.ts

@@ -0,0 +1,425 @@
+/**
+ * Convert a string secret to a Uint8Array key for jose.
+ * Uses the raw bytes of the secret (UTF-8 encoded).
+ */
+declare function secretToKey(secret: string): Uint8Array;
+/**
+ * Sign a JWT access token.
+ *
+ * @param claims - The payload claims (from buildClaims)
+ * @param secret - The NEXTLY_SECRET string
+ * @param ttlSeconds - Token TTL in seconds (default 900 = 15 minutes)
+ * @returns Signed JWT string
+ */
+declare function signAccessToken(claims: Record<string, unknown>, secret: string, ttlSeconds?: number): Promise<string>;
+
+interface NextlyJwtPayload {
+    sub: string;
+    iat: number;
+    exp: number;
+    jti: string;
+    email: string;
+    name: string;
+    image: string | null;
+    roleIds: string[];
+    [key: string]: unknown;
+}
+interface BuildClaimsInput {
+    userId: string;
+    email: string;
+    name: string;
+    image: string | null;
+    roleIds: string[];
+    customFields?: Record<string, unknown>;
+}
+/**
+ * Build JWT claims from user data.
+ * Does NOT set iat/exp/jti -- those are set by the signing function.
+ */
+declare function buildClaims(input: BuildClaimsInput): Record<string, unknown>;
+
+type VerifyResult = {
+    valid: true;
+    payload: NextlyJwtPayload;
+} | {
+    valid: false;
+    reason: "expired" | "invalid" | "malformed";
+};
+/**
+ * Verify and decode a JWT access token.
+ *
+ * @param token - The JWT string from the cookie
+ * @param secret - The NEXTLY_SECRET string
+ * @returns VerifyResult with payload on success or reason on failure
+ */
+declare function verifyAccessToken(token: string, secret: string): Promise<VerifyResult>;
+
+interface SessionUser {
+    id: string;
+    email: string;
+    name: string;
+    image: string | null;
+    roleIds: string[];
+    /** Custom user fields from user_ext table */
+    [key: string]: unknown;
+}
+interface AuthContext {
+    userId: string;
+    userName: string;
+    userEmail: string;
+    permissions: Map<string, boolean>;
+    roles: string[];
+    authMethod: "session" | "api-key";
+}
+interface RefreshTokenRecord {
+    id: string;
+    userId: string;
+    tokenHash: string;
+    userAgent: string | null;
+    ipAddress: string | null;
+    expiresAt: Date;
+    createdAt: Date;
+}
+
+type GetSessionResult = {
+    authenticated: true;
+    user: SessionUser;
+} | {
+    authenticated: false;
+    reason: "no_token" | "expired" | "invalid";
+};
+/**
+ * Extract and verify the session from a request.
+ * No database hit -- purely stateless JWT verification.
+ */
+declare function getSession(request: Request, secret: string): Promise<GetSessionResult>;
+/**
+ * Check if a session user has a specific role.
+ */
+declare function hasRole(user: SessionUser, roleSlug: string): boolean;
+/**
+ * Check if a session user has any of the specified roles.
+ */
+declare function hasAnyRole(user: SessionUser, roleSlugs: string[]): boolean;
+/**
+ * Check if a session user has all of the specified roles.
+ */
+declare function hasAllRoles(user: SessionUser, roleSlugs: string[]): boolean;
+
+/**
+ * Generate a new opaque refresh token (64 bytes, hex-encoded = 128 chars).
+ */
+declare function generateRefreshToken(): string;
+/**
+ * Hash a refresh token using SHA-256 for database storage.
+ * We use SHA-256 (not bcrypt) because refresh tokens have high entropy (64 bytes).
+ */
+declare function hashRefreshToken(token: string): string;
+
+/**
+ * Require a valid session. Returns the session user or throws
+ * `NextlyError.authRequired()`.
+ */
+declare function requireAuth(request: Request, secret: string): Promise<SessionUser>;
+
+/**
+ * Require a specific role. Throws `NextlyError.forbidden()` if missing.
+ *
+ * Public message comes from the factory ("You don't have permission to
+ * perform this action."). The required role identity is recorded in
+ * logContext only; the wire response never includes it (spec §13.7).
+ */
+declare function requireRole(user: SessionUser, roleSlug: string): void;
+/**
+ * Require any of the specified roles. Throws `NextlyError.forbidden()` if
+ * none match. The role list lives in logContext per spec §13.7;
+ * the wire response never includes it.
+ */
+declare function requireAnyRole(user: SessionUser, roleSlugs: string[]): void;
+/**
+ * Require all of the specified roles. Throws `NextlyError.forbidden()` if
+ * any are missing. The role list lives in logContext per spec §13.7.
+ */
+declare function requireAllRoles(user: SessionUser, roleSlugs: string[]): void;
+
+interface ErrorResponse {
+    success: false;
+    statusCode: number;
+    message: string;
+    error: string;
+    data: null;
+    headers?: Record<string, string>;
+}
+/**
+ * Create a JSON error response object.
+ */
+declare function createErrorResponse(statusCode: number, message: string, error: string): ErrorResponse;
+/**
+ * Create a JSON Response from an ErrorResponse.
+ */
+declare function createJsonErrorResponse(errResp: ErrorResponse): Response;
+/**
+ * Check if a value is an ErrorResponse.
+ */
+declare function isErrorResponse(value: unknown): value is ErrorResponse;
+/**
+ * Check a single permission against an AuthContext.
+ * For session auth: delegates to RBAC service.
+ * For API key auth: checks pre-resolved permissions map.
+ */
+declare function checkPermission(context: AuthContext, action: string, resource: string, deps: {
+    checkUserPermission?: (userId: string, action: string, resource: string) => Promise<boolean>;
+}): Promise<boolean>;
+
+/**
+ * Attempt API key authentication from the Authorization header.
+ * Returns null if no Bearer token present (not an error -- caller should try session auth).
+ * Returns ErrorResponse if token is present but invalid/expired/rate-limited.
+ * Returns AuthContext on success.
+ */
+declare function authenticateApiKey(request: Request, deps: {
+    validateApiKey: (rawKey: string) => Promise<{
+        valid: boolean;
+        userId?: string;
+        permissions?: Map<string, boolean>;
+        roles?: string[];
+        error?: string;
+        retryAfter?: number;
+    }>;
+}): Promise<AuthContext | ErrorResponse | null>;
+
+/**
+ * Check if a user has the super-admin role.
+ *
+ * Resolves the user's full role set (direct + inherited) and checks
+ * if any role has the `super-admin` slug. Results are cached in-memory
+ * for 60 seconds.
+ *
+ * @param userId - The user ID to check
+ * @returns `true` if the user has the super-admin role
+ *
+ * @example
+ * ```typescript
+ * if (await isSuperAdmin(userId)) {
+ *   // Bypass all access checks
+ * }
+ * ```
+ */
+declare function isSuperAdmin(userId: string): Promise<boolean>;
+
+type CollectionOperation = "create" | "read" | "update" | "delete";
+interface CollectionAccessDeps {
+    /** Check a user's permission via RBAC service */
+    checkUserPermission?: (userId: string, action: string, resource: string) => Promise<boolean>;
+    /** Evaluate code-defined access function from defineCollection */
+    evaluateCodeAccess?: (collectionSlug: string, operation: CollectionOperation, context: AuthContext) => Promise<boolean | null>;
+}
+/**
+ * Check if the auth context has access to a collection operation.
+ * Priority: super-admin bypass > code-defined access > database RBAC.
+ */
+declare function checkCollectionAccess(context: AuthContext, collectionSlug: string, operation: CollectionOperation, deps: CollectionAccessDeps): Promise<boolean>;
+
+declare function hashPassword(plain: string, saltRounds?: number): Promise<string>;
+declare function verifyPassword(plain: string, hash: string): Promise<boolean>;
+type PasswordStrengthResult = {
+    ok: true;
+    errors?: undefined;
+} | {
+    ok: false;
+    errors: string[];
+};
+declare function validatePasswordStrength(password: string): PasswordStrengthResult;
+
+/**
+ * Single entry point for security-sensitive event recording. Callers
+ * pass a structured event; the writer persists it to the `audit_log`
+ * table via the database adapter.
+ *
+ * Behaviour contract:
+ *
+ *   - **Never throws.** Auth handlers must not fail-open or fail-closed
+ *     because the audit table is unreachable. A DB failure logs a
+ *     structured warning via `getNextlyLogger()` and the request
+ *     continues.
+ *   - **Append-only by application convention.** Operators are expected
+ *     to revoke UPDATE / DELETE GRANTs on the table in production for
+ *     stricter integrity. The writer never offers an update path.
+ *   - **Metadata is opaque JSON.** The `metadata` field stays generic
+ *     so we can extend coverage without a migration each time. Callers
+ *     pass dialect-portable JSON-serialisable values only.
+ *
+ * Hash-chained tamper-evidence (each row signs (prev_hash, this_row))
+ * is intentionally deferred — under concurrent auth events the chain
+ * needs a lock-around-write that complicates the hot path. Operators
+ * who need cryptographic integrity right now should rely on DB-level
+ *
+ * @module domains/audit/audit-log-writer
+ * @since 1.0.0
+ */
+type AuditEventKind = "csrf-failed" | "login-failed" | "password-changed" | "role-assigned" | "role-revoked" | "user-deleted";
+interface AuditEvent {
+    kind: AuditEventKind;
+    /** The user performing the action; null when unauthenticated (failed login, failed CSRF). */
+    actorUserId?: string | null;
+    /** The user being acted on; null when not account-scoped. */
+    targetUserId?: string | null;
+    ipAddress?: string | null;
+    userAgent?: string | null;
+    /** JSON-serialisable details. Goes into the dialect's JSON column. */
+    metadata?: Record<string, unknown>;
+}
+interface AuditLogWriter {
+    write(event: AuditEvent): Promise<void>;
+}
+
+/**
+ * Combined dependency interface for all auth handlers.
+ * Defined as a standalone interface (not multi-extends) to avoid TS2320 conflicts
+ * where the same method name has different return types across handler deps.
+ * The route handler builds this from the DI container services and config.
+ */
+interface AuthRouterDeps {
+    secret: string;
+    isProduction: boolean;
+    accessTokenTTL: number;
+    refreshTokenTTL: number;
+    maxLoginAttempts: number;
+    lockoutDurationSeconds: number;
+    loginStallTimeMs: number;
+    requireEmailVerification: boolean;
+    /**
+     * Spec §13.2 opt-in flag. When false (the spec default), email-conflict
+     * registrations silent-success with a generic message. When true, the
+     * handler returns 409 DUPLICATE so the user knows the email is in use
+     * (trades enumeration risk for UX).
+     */
+    revealRegistrationConflict: boolean;
+    /**
+     * Dev-only auto-login config (config.admin.devAutoLogin). Hard-blocked
+     * at runtime when isProduction is true. When set, the session handler
+     * issues a real session for the named user on the first /admin visit
+     * if no valid session is present. See packages/nextly/src/auth/handlers/session.ts.
+     */
+    devAutoLogin: false | {
+        email: string;
+        password?: string;
+    };
+    allowedOrigins: string[];
+    /**
+     * When true, client-IP resolution honors `X-Forwarded-For` (filtered
+     * through `trustedProxyIps`). When false (default), proxy headers are
+     * ignored.
+     */
+    trustProxy: boolean;
+    /** CIDR list of proxy IPs (from TRUSTED_PROXY_IPS). */
+    trustedProxyIps: string[];
+    /**
+     * Per-IP rate limit on auth write endpoints. `requestsPerHour: 0`
+     * disables the envelope. Single shared bucket across login / register
+     * / forgot-password / reset-password per IP.
+     */
+    authRateLimit: {
+        requestsPerHour: number;
+        windowMs: number;
+    };
+    /**
+     * Writer for security-sensitive auth events. Handlers call
+     * `auditLog.write(...)` on failed CSRF, failed login, password change,
+     * role mutation, and user delete. Writer is fail-safe; any DB error
+     * logs a warning and the request continues.
+     */
+    auditLog: AuditLogWriter;
+    findUserByEmail: (email: string) => Promise<{
+        id: string;
+        email: string;
+        name: string;
+        image: string | null;
+        passwordHash: string;
+        emailVerified: Date | null;
+        isActive: boolean;
+        failedLoginAttempts: number;
+        lockedUntil: Date | null;
+    } | null>;
+    findUserById: (userId: string) => Promise<{
+        id: string;
+        email: string;
+        name: string;
+        image: string | null;
+        isActive: boolean;
+    } | null>;
+    incrementFailedAttempts: (userId: string) => Promise<void>;
+    lockAccount: (userId: string, lockedUntil: Date) => Promise<void>;
+    resetFailedAttempts: (userId: string) => Promise<void>;
+    fetchRoleIds: (userId: string) => Promise<string[]>;
+    fetchCustomFields: (userId: string) => Promise<Record<string, unknown>>;
+    storeRefreshToken: (record: {
+        id: string;
+        userId: string;
+        tokenHash: string;
+        userAgent: string | null;
+        ipAddress: string | null;
+        expiresAt: Date;
+    }) => Promise<void>;
+    findRefreshTokenByHash: (tokenHash: string) => Promise<{
+        id: string;
+        userId: string;
+        expiresAt: Date;
+        userAgent: string | null;
+        ipAddress: string | null;
+    } | null>;
+    deleteRefreshToken: (id: string) => Promise<void>;
+    deleteRefreshTokenByHash: (tokenHash: string) => Promise<void>;
+    deleteAllRefreshTokensForUser: (userId: string) => Promise<void>;
+    getUserCount: () => Promise<number>;
+    createSuperAdmin: (data: {
+        email: string;
+        name: string;
+        password: string;
+    }) => Promise<{
+        id: string;
+        email: string;
+        name: string;
+    }>;
+    seedPermissions: () => Promise<void>;
+    registerUser: (data: {
+        email: string;
+        password: string;
+        name: string;
+    }) => Promise<{
+        id: string;
+        email: string;
+        name: string | null;
+    }>;
+    generatePasswordResetToken: (email: string, redirectPath?: string) => Promise<{
+        token?: string;
+    }>;
+    resetPasswordWithToken: (token: string, newPassword: string) => Promise<{
+        email: string;
+    }>;
+    changePassword: (userId: string, currentPassword: string, newPassword: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    verifyEmail: (token: string) => Promise<{
+        success: boolean;
+        error?: string;
+        email?: string;
+    }>;
+    resendVerificationEmail: (email: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+/**
+ * Route an auth request to the appropriate handler.
+ * Returns null if the path doesn't match any auth route (caller handles 404).
+ *
+ * @param request - The incoming HTTP request
+ * @param authPath - The path after the auth prefix (e.g., "login", "setup-status")
+ * @param deps - Injected service dependencies
+ */
+declare function routeAuthRequest(request: Request, authPath: string, deps: AuthRouterDeps): Promise<Response | null>;
+
+export { authenticateApiKey, buildClaims, checkCollectionAccess, checkPermission, createErrorResponse, createJsonErrorResponse, generateRefreshToken, getSession, hasAllRoles, hasAnyRole, hasRole, hashPassword, hashRefreshToken, isErrorResponse, isSuperAdmin, requireAllRoles, requireAnyRole, requireAuth, requireRole, routeAuthRequest, secretToKey, signAccessToken, validatePasswordStrength, verifyAccessToken, verifyPassword };
+export type { AuthContext, AuthRouterDeps, BuildClaimsInput, ErrorResponse, GetSessionResult, NextlyJwtPayload, PasswordStrengthResult, RefreshTokenRecord, SessionUser, VerifyResult };

package/dist/auth/index.mjs

@@ -0,0 +1,199 @@
+import {
+  routeAuthRequest
+} from "../chunk-A3WPLSDT.mjs";
+import "../chunk-DXGGXIUZ.mjs";
+import "../chunk-APKKRD2G.mjs";
+import {
+  generateRefreshToken,
+  getSession,
+  hasAllRoles,
+  hasAnyRole,
+  hasRole,
+  hashRefreshToken
+} from "../chunk-UUOFWCM6.mjs";
+import {
+  verifyAccessToken
+} from "../chunk-2ZFKXPQM.mjs";
+import {
+  buildClaims,
+  secretToKey,
+  signAccessToken
+} from "../chunk-X23WKS3Z.mjs";
+import "../chunk-67GXH6PR.mjs";
+import "../chunk-W4MGXIRR.mjs";
+import {
+  hashPassword,
+  isSuperAdmin,
+  validatePasswordStrength,
+  verifyPassword
+} from "../chunk-W5KKPZT5.mjs";
+import "../chunk-56WO4WX7.mjs";
+import "../chunk-2W3DVD7S.mjs";
+import "../chunk-TS7GHTG2.mjs";
+import "../chunk-H26B4FYG.mjs";
+import "../chunk-DP3G27G5.mjs";
+import "../chunk-DV6WVX2Q.mjs";
+import "../chunk-UJ2IMJ4W.mjs";
+import "../chunk-IUDOC7N7.mjs";
+import "../chunk-LAZXX4HR.mjs";
+import "../chunk-D5HQBNUB.mjs";
+import {
+  NextlyError
+} from "../chunk-NRUWQ5Z7.mjs";
+import "../chunk-7P6ASYW6.mjs";
+
+// src/auth/guards/require-auth.ts
+async function requireAuth(request, secret) {
+  const result = await getSession(request, secret);
+  if (!result.authenticated) {
+    throw NextlyError.authRequired({
+      logContext: { reason: result.reason }
+    });
+  }
+  return result.user;
+}
+
+// src/auth/guards/require-role.ts
+function requireRole(user, roleSlug) {
+  if (!hasRole(user, roleSlug)) {
+    throw NextlyError.forbidden({
+      logContext: {
+        action: "require-role",
+        requiredRole: roleSlug,
+        userId: user.id
+      }
+    });
+  }
+}
+function requireAnyRole(user, roleSlugs) {
+  if (!hasAnyRole(user, roleSlugs)) {
+    throw NextlyError.forbidden({
+      logContext: {
+        action: "require-any-role",
+        requiredRoles: roleSlugs,
+        userId: user.id
+      }
+    });
+  }
+}
+function requireAllRoles(user, roleSlugs) {
+  if (!hasAllRoles(user, roleSlugs)) {
+    throw NextlyError.forbidden({
+      logContext: {
+        action: "require-all-roles",
+        requiredRoles: roleSlugs,
+        userId: user.id
+      }
+    });
+  }
+}
+
+// src/auth/guards/require-permission.ts
+function createErrorResponse(statusCode, message, error) {
+  return { success: false, statusCode, message, error, data: null };
+}
+function createJsonErrorResponse(errResp) {
+  const headers = {
+    "Content-Type": "application/json",
+    ...errResp.headers || {}
+  };
+  return new Response(JSON.stringify(errResp), {
+    status: errResp.statusCode,
+    headers
+  });
+}
+function isErrorResponse(value) {
+  return typeof value === "object" && value !== null && "success" in value && value.success === false && "statusCode" in value;
+}
+async function checkPermission(context, action, resource, deps) {
+  if (context.authMethod === "api-key") {
+    const permSlug = `${action}-${resource}`;
+    return context.permissions.get(permSlug) === true;
+  }
+  if (deps.checkUserPermission) {
+    return deps.checkUserPermission(context.userId, action, resource);
+  }
+  return false;
+}
+
+// src/auth/guards/require-api-key.ts
+async function authenticateApiKey(request, deps) {
+  const authHeader = request.headers.get("authorization");
+  if (!authHeader || !authHeader.startsWith("Bearer ")) {
+    return null;
+  }
+  const rawKey = authHeader.slice(7);
+  if (!rawKey) {
+    return createErrorResponse(401, "Missing API key", "Unauthorized");
+  }
+  const result = await deps.validateApiKey(rawKey);
+  if (!result.valid) {
+    if (result.retryAfter) {
+      const resp = createErrorResponse(
+        429,
+        "Rate limit exceeded",
+        "Too Many Requests"
+      );
+      resp.headers = { "Retry-After": String(result.retryAfter) };
+      return resp;
+    }
+    return createErrorResponse(
+      401,
+      result.error || "Invalid API key",
+      "Unauthorized"
+    );
+  }
+  return {
+    userId: result.userId,
+    userName: "",
+    userEmail: "",
+    permissions: result.permissions || /* @__PURE__ */ new Map(),
+    roles: result.roles || [],
+    authMethod: "api-key"
+  };
+}
+
+// src/auth/guards/require-collection-access.ts
+async function checkCollectionAccess(context, collectionSlug, operation, deps) {
+  if (context.roles.includes("super-admin")) {
+    return true;
+  }
+  if (deps.evaluateCodeAccess) {
+    const codeResult = await deps.evaluateCodeAccess(
+      collectionSlug,
+      operation,
+      context
+    );
+    if (codeResult !== null) {
+      return codeResult;
+    }
+  }
+  return checkPermission(context, operation, collectionSlug, deps);
+}
+export {
+  authenticateApiKey,
+  buildClaims,
+  checkCollectionAccess,
+  checkPermission,
+  createErrorResponse,
+  createJsonErrorResponse,
+  generateRefreshToken,
+  getSession,
+  hasAllRoles,
+  hasAnyRole,
+  hasRole,
+  hashPassword,
+  hashRefreshToken,
+  isErrorResponse,
+  isSuperAdmin,
+  requireAllRoles,
+  requireAnyRole,
+  requireAuth,
+  requireRole,
+  routeAuthRequest,
+  secretToKey,
+  signAccessToken,
+  validatePasswordStrength,
+  verifyAccessToken,
+  verifyPassword
+};

package/dist/boot-apply-PQSYLDIN.mjs

@@ -0,0 +1,7 @@
+import {
+  runBootTimeApplyIfDev
+} from "./chunk-R6JJQHFC.mjs";
+import "./chunk-7P6ASYW6.mjs";
+export {
+  runBootTimeApplyIfDev
+};