@webda/core 4.0.0-beta.3 → 4.0.0-beta.5

package/lib/models/permissions.d.ts

@@ -0,0 +1,236 @@
+import { QueryValidator } from "@webda/ql";
+import type { IOperationContext } from "../contexts/icontext.js";
+/**
+ * Result of a model's static `getPermissionQuery(context)`
+ */
+export type PermissionQuery = {
+    /**
+     * WebdaQL filter ANDed with the client query (filter only: no ORDER BY, LIMIT or OFFSET)
+     */
+    query: string;
+    /**
+     * The filter only narrows the results: `canAct(context, "get")` decides for each of them
+     */
+    partial: boolean;
+};
+/**
+ * Whether a model class defines a static `canAct` of its own (not the base one)
+ * @param model - the model class
+ * @returns true when the static form is overridden
+ */
+export declare function hasStaticPermissionCheck(model: any): boolean;
+/**
+ * Whether a model class defines a permission check at all: a static `canAct` of its own (not the base one), or an
+ * instance `canAct`. A model with neither is refused on every transport. Subclasses with their own check do not
+ * open a class that has none: an object reached through a class must be allowed by that class too
+ * @param model - the model class
+ * @returns true when the model defines one of the two forms
+ */
+export declare function hasModelPermissionCheck(model: any): boolean;
+/**
+ * Ask the model whether the current caller may perform `action` on an object
+ *
+ * The question goes through the static `canAct(context, action, object)` of the model class (see
+ * {@link Model.canAct}): the base implementation delegates to the object's instance `canAct`, and denies when there
+ * is none. `true` allows; anything else (`false`, a refusal reason string, `undefined`...) refuses, and so does a
+ * `canAct` that throws.
+ *
+ * @param object - the model instance (the new, unsaved object on create)
+ * @param context - the caller context
+ * @param action - the action name ("get", "create", "update", "delete", an action name or "attribute.action")
+ * @param model - the model class (defaults to the object's class)
+ * @returns true when allowed, otherwise the refusal (a reason string or false)
+ */
+export declare function getModelPermission(object: any, context: IOperationContext, action: string, model?: any): Promise<any>;
+/**
+ * Whether the current caller may perform `action` on a model instance (see {@link checkModelPermission}); it never
+ * throws
+ * @param object - the model instance
+ * @param context - the caller context
+ * @param action - the action name
+ * @param model - the model class (defaults to the object's class)
+ * @returns true when allowed
+ */
+export declare function isModelActionAllowed(object: any, context: IOperationContext, action: string, model?: any): Promise<boolean>;
+/**
+ * Message of the NotFound error for a missing object, also used for an object the caller may not read
+ */
+export declare const NOT_FOUND_MESSAGE = "Object not found";
+/**
+ * Load an object for an action as the caller: a missing object and an object the caller may not read throw the same
+ * `NotFound("Object not found")`; a readable object whose action is refused throws `Forbidden`
+ * @param model - the model class
+ * @param key - the primary key
+ * @param context - the caller context
+ * @param action - the action ("get" to only read)
+ * @returns the object
+ */
+export declare function loadModelForAction<T = any>(model: any, key: any, context: IOperationContext, action: string): Promise<T>;
+/**
+ * The parent relation (`ModelParent`) of a model, if any
+ * @param model - the model class
+ * @returns the parent attribute and model identifier
+ */
+export declare function getParentRelation(model: any): {
+    attribute: string;
+    model: string;
+} | undefined;
+/**
+ * A child can only be attached to a parent the caller may read: a missing parent and an unreadable one throw the same
+ * `NotFound("Object not found")`
+ * @param model - the child model class
+ * @param parentId - the parent primary key
+ * @param context - the caller context
+ */
+export declare function checkModelParent(model: any, parentId: any, context: IOperationContext): Promise<void>;
+/**
+ * When an update moves an object to another parent, the caller must be able to read the new parent
+ * @param model - the model class
+ * @param object - the stored object
+ * @param input - the sanitized update input
+ * @param context - the caller context
+ */
+export declare function checkModelReparent(model: any, object: any, input: any, context: IOperationContext): Promise<void>;
+/**
+ * Enforce a model's permission for an action on an object: the single check used by every client path (REST, gRPC,
+ * MCP, GraphQL and any transport dispatching operations)
+ *
+ * A caller who may not read the object (`canAct(ctx, "get", object)` refused) gets exactly the error of a missing
+ * object (`NotFound("Object not found")`), whatever the action, so a refusal never reveals that the key exists. A
+ * caller who may read the object but not perform the action gets a `Forbidden`. On `"create"` the object does not
+ * exist yet: a refusal is always a `Forbidden`.
+ *
+ * The refusal reason returned by `canAct` is logged, never sent to the client.
+ *
+ * @param object - the model instance
+ * @param context - the caller context
+ * @param action - the action name
+ * @param model - the model class (defaults to the object's class)
+ * @throws WebdaError.NotFound when the caller may not read the object
+ * @throws WebdaError.Forbidden when the caller may read the object but not perform the action
+ */
+export declare function checkModelPermission(object: any, context: IOperationContext, action: string, model?: any): Promise<void>;
+/**
+ * Enforce a model's permission for a static (class-level) action: `canAct(context, action)` without object
+ *
+ * There is no object to hide, so a refusal is always a `Forbidden`.
+ * @param model - the model class
+ * @param context - the caller context
+ * @param action - the action name
+ * @throws WebdaError.Forbidden when refused
+ */
+export declare function checkStaticModelPermission(model: any, context: IOperationContext, action: string): Promise<void>;
+/**
+ * Persist a new object with the repository `create`, which refuses an existing key (atomically in every bundled
+ * repository), instead of `save()`, which upserts
+ * @param object - the new model instance
+ * @returns the object
+ * @throws WebdaError.Conflict when an object with the same primary key exists
+ */
+export declare function createModel<T = any>(object: T): Promise<T>;
+/**
+ * AND the model's permission query into a client query
+ *
+ * Both sides are parsed and combined on the expression tree, so a client `OR` keeps its precedence. The client
+ * ORDER BY, LIMIT and OFFSET are kept.
+ *
+ * @param query - the client query
+ * @param permission - the permission query, if any
+ * @returns the query to run
+ * @throws SyntaxError if the client query is invalid
+ */
+export declare function mergePermissionQuery(query: string, permission?: PermissionQuery | null): string;
+/**
+ * Highest LIMIT a client query can ask for: larger LIMITs are lowered to it
+ */
+export declare const MAX_QUERY_LIMIT = 1000;
+/**
+ * Rows a permission-filtered query scans to fill one page: ten times the page LIMIT, at least
+ * {@link MIN_SCANNED_ROWS}, at most {@link MAX_SCANNED_ROWS}
+ */
+export declare const SCAN_FACTOR = 10;
+/**
+ * Lower bound of the scan budget of a permission-filtered page
+ */
+export declare const MIN_SCANNED_ROWS = 100;
+/**
+ * Absolute bound of the scan budget of a permission-filtered page
+ */
+export declare const MAX_SCANNED_ROWS = 10000;
+/**
+ * Most store pages read to fill one page, whatever their size
+ */
+export declare const MAX_REFILL_PAGES = 100;
+/**
+ * Lifetime of a continuation token (one hour): paging has to resume within it
+ */
+export declare const CONTINUATION_TOKEN_TTL_MS: number;
+/**
+ * Refuse a client query that reads private (`__`-prefixed) fields, at any depth, in its filter or ORDER BY: a filter
+ * on a private field (a password hash...) would reveal its value through which rows match
+ * @param query - the parsed client query
+ * @throws WebdaError.BadRequest when a field path has a `__`-prefixed segment
+ */
+export declare function assertNoPrivateFields(query: QueryValidator): void;
+/**
+ * What a continuation token is bound to: it is only accepted back for the same model, the same query (filter and
+ * ORDER BY) and the same caller
+ */
+export type ContinuationTokenBinding = {
+    /**
+     * Model identifier
+     */
+    model: string;
+    /**
+     * The query the token continues: filter and ORDER BY, without LIMIT and OFFSET
+     */
+    query: string;
+    /**
+     * Caller id, "anonymous" when not logged in
+     */
+    user: string;
+};
+/**
+ * Seal a store continuation token: encrypted with the CryptoService (random IV, padded to 64 bytes) so its value
+ * cannot be read, compared or forged by the client; bound to the model, the query and the caller; and expiring
+ * after `ttl` ({@link CONTINUATION_TOKEN_TTL_MS})
+ * @param token - the store token
+ * @param binding - what the token is bound to
+ * @param ttl - lifetime in milliseconds
+ * @returns the opaque token
+ */
+export declare function sealContinuationToken(token: string, binding: ContinuationTokenBinding, ttl?: number): Promise<string>;
+/**
+ * Open a token produced by {@link sealContinuationToken}
+ * @param token - the opaque token
+ * @param binding - what the token must be bound to
+ * @returns the store token
+ * @throws WebdaError.BadRequest when the token was not produced by this application for this model, query and
+ * caller, or has expired
+ */
+export declare function unsealContinuationToken(token: string, binding: ContinuationTokenBinding): Promise<string>;
+/**
+ * Query a model as the caller
+ *
+ * - the client query may not read private (`__`) fields (400), and its LIMIT is lowered to {@link MAX_QUERY_LIMIT};
+ * - a model defining neither `canAct` form refuses every row: the store is not asked;
+ * - the model's static `getPermissionQuery(context)` is ANDed into the query;
+ * - every result is checked with the static `canAct(context, "get", row)` and refused ones are dropped. Refused rows
+ *   are replaced by continuing the scan (next store pages, asking only for the missing rows), within a budget of
+ *   `SCAN_FACTOR` x LIMIT rows (between `MIN_SCANNED_ROWS` and `MAX_SCANNED_ROWS`) and {@link MAX_REFILL_PAGES}
+ *   store pages. When the budget is spent, an empty page carries no token;
+ * - the continuation token is sealed ({@link sealContinuationToken}): a store token counting or naming rows
+ *   (Postgres/Firestore offsets, Dynamo keys, memory offsets) would otherwise reveal hidden matches. It is bound to
+ *   the model, the query and the caller, expires after {@link CONTINUATION_TOKEN_TTL_MS}, and is sent back as is in
+ *   `OFFSET`; any other value is a 400.
+ *
+ * @param model - the model class
+ * @param query - the client query
+ * @param context - the caller context
+ * @returns the query results the caller may read
+ */
+export declare function queryModelWithPermissions<T = any>(model: any, query: string, context: IOperationContext): Promise<{
+    results: T[];
+    continuationToken?: string;
+}>;
+//# sourceMappingURL=permissions.d.ts.map

package/lib/models/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/models/permissions.ts"],"names":[],"mappings":"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"}