@codixus/server 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Request, Response, NextFunction, Router } from 'express';
 import * as mongodb from 'mongodb';
-import { Document, Collection, Filter, Sort, Db, ClientSession, UpdateFilter, AnyBulkWriteOperation, BulkWriteOptions } from 'mongodb';
+import { Db, Document, Collection, Filter, Sort, ClientSession, UpdateFilter, AnyBulkWriteOperation, BulkWriteOptions } from 'mongodb';
 import { TokenPair, AuthUser } from '@codixus/shared';
 export { ApiResponse, AuthTokenRequest, AuthTokenResponse, AuthUser, CodixusError, DeviceInfo, DeviceMetadata, ErrorCodes, TokenPair, TokenPayload } from '@codixus/shared';
 import { JWTPayload } from 'jose';
@@ -28,6 +28,24 @@ declare class JwtService {
     static hashToken(token: string): string;
 }
 
+interface BannedDevice {
+    _id: string;
+    reason?: string;
+    bannedAt: Date;
+}
+declare class BanService {
+    private collection;
+    private refreshTokensCol;
+    constructor(db: Db);
+    ban(deviceId: string, reason?: string): Promise<void>;
+    unban(deviceId: string): Promise<void>;
+    isBanned(deviceId: string): Promise<boolean>;
+    list(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<BannedDevice[]>;
+}
+
 declare global {
     namespace Express {
         interface Request {
@@ -38,7 +56,7 @@ declare global {
 interface GuardOptions {
     optional?: boolean;
 }
-declare function createGuard(jwt: JwtService): (options?: GuardOptions) => (req: Request, res: Response, next: NextFunction) => Promise<void>;
+declare function createGuard(jwt: JwtService, banService?: BanService): (options?: GuardOptions) => (req: Request, res: Response, next: NextFunction) => Promise<void>;
 
 interface AuthRouterConfig {
     usersCollection: string;
@@ -163,13 +181,88 @@ interface RateLimitConfig {
     message?: string;
 }
 
+/**
+ * A Request on which `req.user` has been populated by `auth.guard()`. Used in
+ * `allowRead` / `allowWrite` / `allowDelete` hook signatures so consumers
+ * don't need `req.user!` non-null assertions at the call site.
+ */
+type AuthenticatedRequest = Request & {
+    user: AuthUser;
+};
+type HookResult = boolean | Promise<boolean>;
+/**
+ * Stable machine-readable codes returned alongside human-readable `error`
+ * strings. Consumers should switch on `code`, not the message.
+ */
+declare const RestErrorCode: {
+    readonly CreateDisabled: "CREATE_DISABLED";
+    readonly UpdateDisabled: "UPDATE_DISABLED";
+    readonly DeleteDisabled: "DELETE_DISABLED";
+    readonly ReadForbidden: "READ_FORBIDDEN";
+    readonly WriteForbidden: "WRITE_FORBIDDEN";
+    readonly DeleteForbidden: "DELETE_FORBIDDEN";
+    readonly NotFound: "NOT_FOUND";
+    readonly InvalidFilter: "INVALID_FILTER";
+    readonly InvalidSort: "INVALID_SORT";
+    readonly InvalidCursor: "INVALID_CURSOR";
+    readonly InvalidUpdate: "INVALID_UPDATE";
+    readonly InvalidBody: "INVALID_BODY";
+    readonly AuthRequired: "AUTH_REQUIRED";
+};
+type RestErrorCode = (typeof RestErrorCode)[keyof typeof RestErrorCode];
 interface RestOptions {
     allowCreate?: boolean;
     allowUpdate?: boolean;
-    allowDelete?: boolean | ((req: Request, doc: Record<string, unknown>) => boolean);
+    /**
+     * `true`/`false` toggles delete. A function form receives the current doc
+     * and returns whether the caller is allowed to delete it (useful for
+     * "author can delete own post" rules).
+     */
+    allowDelete?: boolean | ((req: AuthenticatedRequest, doc: Record<string, unknown>) => HookResult);
     maxLimit?: number;
     defaultLimit?: number;
     defaultSort?: Record<string, 1 | -1>;
+    /**
+     * Field used to scope rows to a tenant/owner. When set, every
+     * GET /:id, PATCH /:id, DELETE /:id, and list/count filter is forced
+     * to include `{ [ownershipField]: req.user.deviceId }`. Without this
+     * option the handlers are unscoped (IDOR-prone). Set to `"_id"` for
+     * self-only collections (like users), or `"authorId"` for per-author data.
+     *
+     * @example
+     *   // Users can only read/update/delete themselves
+     *   codixus.rest(User, { ownershipField: "_id" })
+     *
+     *   // Posts are scoped by authorId
+     *   codixus.rest(Post, { ownershipField: "authorId" })
+     */
+    ownershipField?: string;
+    /** Top-level keys allowed inside the filter query parameter. */
+    queryableFields?: string[];
+    /** Field names allowed as sort keys (for `?sort=` and cursor pagination). */
+    sortableFields?: string[];
+    /** Whitelist of fields writable through PATCH. Reject any others. */
+    writableFields?: string[];
+    /** Projection for GET responses. Only these fields are returned (plus `_id`). */
+    publicFields?: string[];
+    /**
+     * Comparison operators allowed inside filter values. Defaults to a safe set:
+     * `$eq, $ne, $in, $nin, $gt, $gte, $lt, $lte`. Dangerous operators like
+     * `$where`, `$regex`, `$expr` are rejected by default.
+     */
+    allowedOperators?: string[];
+    /**
+     * Optional hook — return `false` (or a Promise resolving to `false`) to deny
+     * GET /:id after ownership passes. Async is supported so consumers can do
+     * role/team lookups against the DB. Note: if guard middleware didn't run,
+     * `req.user` may be undefined; check before relying on it.
+     */
+    allowRead?: (req: AuthenticatedRequest, doc: Record<string, unknown>) => HookResult;
+    /**
+     * Optional hook — return `false` (or a Promise resolving to `false`) to deny
+     * PATCH /:id after ownership passes. See `allowRead` for async notes.
+     */
+    allowWrite?: (req: AuthenticatedRequest, doc: Record<string, unknown>, patch: Record<string, unknown>) => HookResult;
 }
 
 interface CodixusServerConfig {
@@ -237,4 +330,4 @@ declare class CodixusServer {
 
 declare function validate<T extends z.ZodType>(schema: T): (req: Request, res: Response, next: NextFunction) => void;
 
-export { type AuthRouterConfig, CodixusServer, type CodixusServerConfig, type GuardOptions, Model, type ModelDefinition, type ModelType, Query, type RateLimitConfig, type RestOptions, type SigningConfig, SubCollection, model, validate };
+export { type AuthRouterConfig, type AuthenticatedRequest, CodixusServer, type CodixusServerConfig, type GuardOptions, Model, type ModelDefinition, type ModelType, Query, type RateLimitConfig, RestErrorCode, type RestOptions, type SigningConfig, SubCollection, model, validate };