@qodalis/cli-files 2.0.0-beta.13 → 2.0.0-beta.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qodalis/cli-files",
-  "version": "2.0.0-beta.13",
+  "version": "2.0.0-beta.14",
   "description": "@qodalis/cli extension for Linux file management commands with in-memory filesystem.",
   "author": "Nicolae Lupei, Qodalis Solutions",
   "license": "MIT",
@@ -23,7 +23,7 @@
   "umd": "./umd/index.global.js",
   "unpkg": "./umd/index.global.js",
   "dependencies": {
-    "@qodalis/cli-core": "2.0.0-beta.13"
+    "@qodalis/cli-core": "2.0.0-beta.14"
   },
   "sideEffects": false,
   "main": "./public-api.js",

package/public-api.d.mts

@@ -1,5 +1,5 @@
 import * as _qodalis_cli_core from '@qodalis/cli-core';
-import { ICliOwnership, ICliCommandProcessor, CliProcessCommand, ICliExecutionContext, CliHeadersProvider, ICliFileTransferService, ICliFileEntry, ICliCompletionProvider, ICliCompletionContext, ICliConfigurableModule } from '@qodalis/cli-core';
+import { ICliOwnership, CliAccessAction, ICliCommandProcessor, CliProcessCommand, ICliExecutionContext, CliHeadersProvider, ICliFileTransferService, ICliFileEntry, ICliCompletionProvider, ICliCompletionContext, ICliConfigurableModule } from '@qodalis/cli-core';
 import { Subscription } from 'rxjs';
 
 /**
@@ -29,6 +29,17 @@ interface IFileNode {
 }
 
 declare const IFileSystemService_TOKEN = "cli-file-system-service";
+/**
+ * Decides whether the current principal may act on a node. Set by the files
+ * module from the generic authorization layer (`cliCanAccess`); when no policy
+ * is set (no auth module loaded) every operation is allowed.
+ */
+interface CliFileAccessPolicy {
+    /** rwx check on a file or directory */
+    canAccess(node: IFileNode, action: CliAccessAction): boolean;
+    /** May the principal chmod/chown this node (owner, or `files:chown` / `files:admin`) */
+    canChangeOwnership(node: IFileNode, newOwnership?: ICliOwnership): boolean;
+}
 /**
  * Abstraction for virtual filesystem operations.
  */
@@ -52,6 +63,17 @@ interface IFileSystemService {
     move(src: string, dest: string): void;
     chmod(path: string, permissions: string): void;
     chown(path: string, ownership: ICliOwnership): void;
+    setAccessPolicy?(policy?: CliFileAccessPolicy): void;
+    /** False when the current principal may not reach `path` (needs `x` on every parent) */
+    canTraverse?(path: string): boolean;
+    /** Run `fn` without access checks (system tasks such as creating home directories) */
+    runAsSystem?<T>(fn: () => T): T;
+    /**
+     * System task (no access checks): give every node owned by `fromUid`
+     * (case-insensitive) to `toUid`, e.g. after a user was renamed or deleted.
+     * Returns the number of nodes changed.
+     */
+    reassignOwner?(fromUid: string, toUid: string): number;
     initialize(): Promise<void>;
     persist(): Promise<void>;
 }
@@ -256,6 +278,8 @@ declare class CliTreeCommandProcessor implements ICliCommandProcessor {
         type: "number";
     }[];
     processCommand(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
+    /** File system of the running command (listing goes through access checks) */
+    private fs?;
     private printTree;
 }
 
@@ -349,6 +373,8 @@ declare class CliFindCommandProcessor implements ICliCommandProcessor {
     processCommand(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
     private parseSearchPath;
     private globToRegex;
+    /** File system of the running command (listing goes through access checks) */
+    private fs?;
     private walk;
 }
 
@@ -635,6 +661,8 @@ declare class CliDuCommandProcessor implements ICliCommandProcessor {
     })[];
     processCommand(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
     private parseArgs;
+    /** File system of the running command (listing goes through access checks) */
+    private fs?;
     private collectSizes;
     private formatSize;
 }
@@ -845,12 +873,33 @@ declare class CliShCommandProcessor implements ICliCommandProcessor {
  */
 declare function executeScript(content: string, context: ICliExecutionContext): Promise<void>;
 
+/** Owner of system directories and of legacy nodes created without an owner */
+declare const SYSTEM_OWNERSHIP: ICliOwnership;
+/** Owner of files created while nobody is signed in */
+declare const ANONYMOUS_OWNERSHIP: ICliOwnership;
 declare class IndexedDbFileSystemService implements IFileSystemService {
     private root;
     private cwd;
     private homePath;
     private currentUid;
     private currentGroups;
+    private accessPolicy?;
+    private systemDepth;
+    setAccessPolicy(policy?: CliFileAccessPolicy): void;
+    runAsSystem<T>(fn: () => T): T;
+    reassignOwner(fromUid: string, toUid: string): number;
+    canTraverse(path: string): boolean;
+    private get enforcing();
+    private deny;
+    /** `x` on every existing directory on the way to `resolved` (excluding the target). */
+    private assertTraverse;
+    private assertAccess;
+    /** Recursive delete: every directory inside must allow removing its entries (`w` + `x`, readable). */
+    private assertRemovableTree;
+    /** Copying reads everything it copies: `r` on every file, `r` + `x` on every directory. */
+    private assertReadableTree;
+    /** Creating/removing entries needs `w` and `x` on the containing directory. */
+    private assertModifyDir;
     setCurrentUser(uid: string, groups: string[]): void;
     private getDefaultOwnership;
     getCurrentDirectory(): string;
@@ -873,6 +922,8 @@ declare class IndexedDbFileSystemService implements IFileSystemService {
     chown(path: string, ownership: ICliOwnership): void;
     initialize(): Promise<void>;
     persist(): Promise<void>;
+    /** A copy belongs to whoever made it (like `cp` without `-p`) */
+    private ownedByCurrentUser;
     private cloneNode;
     private openDb;
     private idbGet;
@@ -969,6 +1020,35 @@ declare class VirtualFsFileTransferService implements ICliFileTransferService {
     } | null>;
 }
 
+/** Permissions the files module understands. */
+declare const CliFilesPermissions: {
+    /** Bypass all file permission checks */
+    readonly Admin: "files:admin";
+    /** chmod/chown files you do not own */
+    readonly Chown: "files:chown";
+};
+/** Mode for newly created home directories (owner full, group read/traverse) */
+declare const HOME_DIR_PERMISSIONS = "rwxr-x---";
+/**
+ * Access policy built on the generic authorization layer. Allows everything
+ * when no authorization service is registered (no auth module loaded).
+ */
+declare function createFileAccessPolicy(context: ICliExecutionContext): CliFileAccessPolicy;
+/**
+ * Follow the signed-in user (from any auth module that provides
+ * {@link ICliUserSessionService}): ownership for new files, home directory
+ * creation and `~`, and moving to the home directory when the user changes.
+ */
+declare function followUserSession(context: ICliExecutionContext, fs: IFileSystemService): Subscription | undefined;
+/**
+ * Keep file ownership (stored by login name) in step with the accounts of
+ * any auth module that emits {@link ICliUserEventService} events: a rename
+ * moves the user's files to the new name, a deletion gives them to `root`, so
+ * a later account with the same name never inherits them. Runs as a system
+ * task (no rwx checks for the acting user). No-op without such a module.
+ */
+declare function followUserAccounts(context: ICliExecutionContext, fs: IFileSystemService): Subscription | undefined;
+
 /**
  * Provides tab-completion for file and directory names from the virtual filesystem.
  * Priority 50 (checked before command/parameter providers for file-related commands).
@@ -994,7 +1074,11 @@ interface CliFilesModuleConfig {
 interface ICliFilesModule extends ICliConfigurableModule<CliFilesModuleConfig> {
     /** Subscription for drag-and-drop file uploads, cleaned up in onDestroy */
     _dragDropSubscription?: Subscription;
+    /** Subscription following the signed-in user, cleaned up in onDestroy */
+    _sessionSubscription?: Subscription;
+    /** Subscription following account renames/deletions, cleaned up in onDestroy */
+    _accountsSubscription?: Subscription;
 }
 declare const filesModule: ICliFilesModule;
 
-export { CliAwkCommandProcessor, CliBasenameCommandProcessor, CliCatCommandProcessor, CliCdCommandProcessor, CliChmodCommandProcessor, CliChownCommandProcessor, CliCpCommandProcessor, CliCutCommandProcessor, CliDiffCommandProcessor, CliDirnameCommandProcessor, CliDuCommandProcessor, CliEchoCommandProcessor, type CliFilesModuleConfig, CliFindCommandProcessor, CliGrepCommandProcessor, CliHeadCommandProcessor, CliLnCommandProcessor, CliLsCommandProcessor, CliMkdirCommandProcessor, CliMvCommandProcessor, CliPasteCommandProcessor, CliPwdCommandProcessor, CliRmCommandProcessor, CliRmdirCommandProcessor, CliSedCommandProcessor, CliShCommandProcessor, CliSortCommandProcessor, CliStatCommandProcessor, CliTacCommandProcessor, CliTailCommandProcessor, CliTeeCommandProcessor, CliTouchCommandProcessor, CliTrCommandProcessor, CliTreeCommandProcessor, CliUniqCommandProcessor, CliWcCommandProcessor, CliXargsCommandProcessor, FilePathCompletionProvider, type IFileNode, type IFileSystemService, IFileSystemService_TOKEN, IndexedDbFileSystemService, type ServerFileSystemOptions, ServerFileSystemService, VirtualFsFileTransferService, executeScript, filesModule };
+export { ANONYMOUS_OWNERSHIP, CliAwkCommandProcessor, CliBasenameCommandProcessor, CliCatCommandProcessor, CliCdCommandProcessor, CliChmodCommandProcessor, CliChownCommandProcessor, CliCpCommandProcessor, CliCutCommandProcessor, CliDiffCommandProcessor, CliDirnameCommandProcessor, CliDuCommandProcessor, CliEchoCommandProcessor, type CliFileAccessPolicy, type CliFilesModuleConfig, CliFilesPermissions, CliFindCommandProcessor, CliGrepCommandProcessor, CliHeadCommandProcessor, CliLnCommandProcessor, CliLsCommandProcessor, CliMkdirCommandProcessor, CliMvCommandProcessor, CliPasteCommandProcessor, CliPwdCommandProcessor, CliRmCommandProcessor, CliRmdirCommandProcessor, CliSedCommandProcessor, CliShCommandProcessor, CliSortCommandProcessor, CliStatCommandProcessor, CliTacCommandProcessor, CliTailCommandProcessor, CliTeeCommandProcessor, CliTouchCommandProcessor, CliTrCommandProcessor, CliTreeCommandProcessor, CliUniqCommandProcessor, CliWcCommandProcessor, CliXargsCommandProcessor, FilePathCompletionProvider, HOME_DIR_PERMISSIONS, type IFileNode, type IFileSystemService, IFileSystemService_TOKEN, IndexedDbFileSystemService, SYSTEM_OWNERSHIP, type ServerFileSystemOptions, ServerFileSystemService, VirtualFsFileTransferService, createFileAccessPolicy, executeScript, filesModule, followUserAccounts, followUserSession };

package/public-api.d.ts

@@ -1,5 +1,5 @@
 import * as _qodalis_cli_core from '@qodalis/cli-core';
-import { ICliOwnership, ICliCommandProcessor, CliProcessCommand, ICliExecutionContext, CliHeadersProvider, ICliFileTransferService, ICliFileEntry, ICliCompletionProvider, ICliCompletionContext, ICliConfigurableModule } from '@qodalis/cli-core';
+import { ICliOwnership, CliAccessAction, ICliCommandProcessor, CliProcessCommand, ICliExecutionContext, CliHeadersProvider, ICliFileTransferService, ICliFileEntry, ICliCompletionProvider, ICliCompletionContext, ICliConfigurableModule } from '@qodalis/cli-core';
 import { Subscription } from 'rxjs';
 
 /**
@@ -29,6 +29,17 @@ interface IFileNode {
 }
 
 declare const IFileSystemService_TOKEN = "cli-file-system-service";
+/**
+ * Decides whether the current principal may act on a node. Set by the files
+ * module from the generic authorization layer (`cliCanAccess`); when no policy
+ * is set (no auth module loaded) every operation is allowed.
+ */
+interface CliFileAccessPolicy {
+    /** rwx check on a file or directory */
+    canAccess(node: IFileNode, action: CliAccessAction): boolean;
+    /** May the principal chmod/chown this node (owner, or `files:chown` / `files:admin`) */
+    canChangeOwnership(node: IFileNode, newOwnership?: ICliOwnership): boolean;
+}
 /**
  * Abstraction for virtual filesystem operations.
  */
@@ -52,6 +63,17 @@ interface IFileSystemService {
     move(src: string, dest: string): void;
     chmod(path: string, permissions: string): void;
     chown(path: string, ownership: ICliOwnership): void;
+    setAccessPolicy?(policy?: CliFileAccessPolicy): void;
+    /** False when the current principal may not reach `path` (needs `x` on every parent) */
+    canTraverse?(path: string): boolean;
+    /** Run `fn` without access checks (system tasks such as creating home directories) */
+    runAsSystem?<T>(fn: () => T): T;
+    /**
+     * System task (no access checks): give every node owned by `fromUid`
+     * (case-insensitive) to `toUid`, e.g. after a user was renamed or deleted.
+     * Returns the number of nodes changed.
+     */
+    reassignOwner?(fromUid: string, toUid: string): number;
     initialize(): Promise<void>;
     persist(): Promise<void>;
 }
@@ -256,6 +278,8 @@ declare class CliTreeCommandProcessor implements ICliCommandProcessor {
         type: "number";
     }[];
     processCommand(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
+    /** File system of the running command (listing goes through access checks) */
+    private fs?;
     private printTree;
 }
 
@@ -349,6 +373,8 @@ declare class CliFindCommandProcessor implements ICliCommandProcessor {
     processCommand(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
     private parseSearchPath;
     private globToRegex;
+    /** File system of the running command (listing goes through access checks) */
+    private fs?;
     private walk;
 }
 
@@ -635,6 +661,8 @@ declare class CliDuCommandProcessor implements ICliCommandProcessor {
     })[];
     processCommand(command: CliProcessCommand, context: ICliExecutionContext): Promise<void>;
     private parseArgs;
+    /** File system of the running command (listing goes through access checks) */
+    private fs?;
     private collectSizes;
     private formatSize;
 }
@@ -845,12 +873,33 @@ declare class CliShCommandProcessor implements ICliCommandProcessor {
  */
 declare function executeScript(content: string, context: ICliExecutionContext): Promise<void>;
 
+/** Owner of system directories and of legacy nodes created without an owner */
+declare const SYSTEM_OWNERSHIP: ICliOwnership;
+/** Owner of files created while nobody is signed in */
+declare const ANONYMOUS_OWNERSHIP: ICliOwnership;
 declare class IndexedDbFileSystemService implements IFileSystemService {
     private root;
     private cwd;
     private homePath;
     private currentUid;
     private currentGroups;
+    private accessPolicy?;
+    private systemDepth;
+    setAccessPolicy(policy?: CliFileAccessPolicy): void;
+    runAsSystem<T>(fn: () => T): T;
+    reassignOwner(fromUid: string, toUid: string): number;
+    canTraverse(path: string): boolean;
+    private get enforcing();
+    private deny;
+    /** `x` on every existing directory on the way to `resolved` (excluding the target). */
+    private assertTraverse;
+    private assertAccess;
+    /** Recursive delete: every directory inside must allow removing its entries (`w` + `x`, readable). */
+    private assertRemovableTree;
+    /** Copying reads everything it copies: `r` on every file, `r` + `x` on every directory. */
+    private assertReadableTree;
+    /** Creating/removing entries needs `w` and `x` on the containing directory. */
+    private assertModifyDir;
     setCurrentUser(uid: string, groups: string[]): void;
     private getDefaultOwnership;
     getCurrentDirectory(): string;
@@ -873,6 +922,8 @@ declare class IndexedDbFileSystemService implements IFileSystemService {
     chown(path: string, ownership: ICliOwnership): void;
     initialize(): Promise<void>;
     persist(): Promise<void>;
+    /** A copy belongs to whoever made it (like `cp` without `-p`) */
+    private ownedByCurrentUser;
     private cloneNode;
     private openDb;
     private idbGet;
@@ -969,6 +1020,35 @@ declare class VirtualFsFileTransferService implements ICliFileTransferService {
     } | null>;
 }
 
+/** Permissions the files module understands. */
+declare const CliFilesPermissions: {
+    /** Bypass all file permission checks */
+    readonly Admin: "files:admin";
+    /** chmod/chown files you do not own */
+    readonly Chown: "files:chown";
+};
+/** Mode for newly created home directories (owner full, group read/traverse) */
+declare const HOME_DIR_PERMISSIONS = "rwxr-x---";
+/**
+ * Access policy built on the generic authorization layer. Allows everything
+ * when no authorization service is registered (no auth module loaded).
+ */
+declare function createFileAccessPolicy(context: ICliExecutionContext): CliFileAccessPolicy;
+/**
+ * Follow the signed-in user (from any auth module that provides
+ * {@link ICliUserSessionService}): ownership for new files, home directory
+ * creation and `~`, and moving to the home directory when the user changes.
+ */
+declare function followUserSession(context: ICliExecutionContext, fs: IFileSystemService): Subscription | undefined;
+/**
+ * Keep file ownership (stored by login name) in step with the accounts of
+ * any auth module that emits {@link ICliUserEventService} events: a rename
+ * moves the user's files to the new name, a deletion gives them to `root`, so
+ * a later account with the same name never inherits them. Runs as a system
+ * task (no rwx checks for the acting user). No-op without such a module.
+ */
+declare function followUserAccounts(context: ICliExecutionContext, fs: IFileSystemService): Subscription | undefined;
+
 /**
  * Provides tab-completion for file and directory names from the virtual filesystem.
  * Priority 50 (checked before command/parameter providers for file-related commands).
@@ -994,7 +1074,11 @@ interface CliFilesModuleConfig {
 interface ICliFilesModule extends ICliConfigurableModule<CliFilesModuleConfig> {
     /** Subscription for drag-and-drop file uploads, cleaned up in onDestroy */
     _dragDropSubscription?: Subscription;
+    /** Subscription following the signed-in user, cleaned up in onDestroy */
+    _sessionSubscription?: Subscription;
+    /** Subscription following account renames/deletions, cleaned up in onDestroy */
+    _accountsSubscription?: Subscription;
 }
 declare const filesModule: ICliFilesModule;
 
-export { CliAwkCommandProcessor, CliBasenameCommandProcessor, CliCatCommandProcessor, CliCdCommandProcessor, CliChmodCommandProcessor, CliChownCommandProcessor, CliCpCommandProcessor, CliCutCommandProcessor, CliDiffCommandProcessor, CliDirnameCommandProcessor, CliDuCommandProcessor, CliEchoCommandProcessor, type CliFilesModuleConfig, CliFindCommandProcessor, CliGrepCommandProcessor, CliHeadCommandProcessor, CliLnCommandProcessor, CliLsCommandProcessor, CliMkdirCommandProcessor, CliMvCommandProcessor, CliPasteCommandProcessor, CliPwdCommandProcessor, CliRmCommandProcessor, CliRmdirCommandProcessor, CliSedCommandProcessor, CliShCommandProcessor, CliSortCommandProcessor, CliStatCommandProcessor, CliTacCommandProcessor, CliTailCommandProcessor, CliTeeCommandProcessor, CliTouchCommandProcessor, CliTrCommandProcessor, CliTreeCommandProcessor, CliUniqCommandProcessor, CliWcCommandProcessor, CliXargsCommandProcessor, FilePathCompletionProvider, type IFileNode, type IFileSystemService, IFileSystemService_TOKEN, IndexedDbFileSystemService, type ServerFileSystemOptions, ServerFileSystemService, VirtualFsFileTransferService, executeScript, filesModule };
+export { ANONYMOUS_OWNERSHIP, CliAwkCommandProcessor, CliBasenameCommandProcessor, CliCatCommandProcessor, CliCdCommandProcessor, CliChmodCommandProcessor, CliChownCommandProcessor, CliCpCommandProcessor, CliCutCommandProcessor, CliDiffCommandProcessor, CliDirnameCommandProcessor, CliDuCommandProcessor, CliEchoCommandProcessor, type CliFileAccessPolicy, type CliFilesModuleConfig, CliFilesPermissions, CliFindCommandProcessor, CliGrepCommandProcessor, CliHeadCommandProcessor, CliLnCommandProcessor, CliLsCommandProcessor, CliMkdirCommandProcessor, CliMvCommandProcessor, CliPasteCommandProcessor, CliPwdCommandProcessor, CliRmCommandProcessor, CliRmdirCommandProcessor, CliSedCommandProcessor, CliShCommandProcessor, CliSortCommandProcessor, CliStatCommandProcessor, CliTacCommandProcessor, CliTailCommandProcessor, CliTeeCommandProcessor, CliTouchCommandProcessor, CliTrCommandProcessor, CliTreeCommandProcessor, CliUniqCommandProcessor, CliWcCommandProcessor, CliXargsCommandProcessor, FilePathCompletionProvider, HOME_DIR_PERMISSIONS, type IFileNode, type IFileSystemService, IFileSystemService_TOKEN, IndexedDbFileSystemService, SYSTEM_OWNERSHIP, type ServerFileSystemOptions, ServerFileSystemService, VirtualFsFileTransferService, createFileAccessPolicy, executeScript, filesModule, followUserAccounts, followUserSession };