@tnnevol/dsh-fnos 0.1.1-rc.2.0

package/lib/index.d.ts

@@ -0,0 +1,125 @@
+import z from "@deepseek-ai/schemastery";
+import { IncomingMessage } from "node:http";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/authorized-directories-contract.d.ts
+/** Browser/Host contract for fnOS shared-directory management. */
+/** Settings namespace used to pair the Host namespace with the Client card. */
+declare const FNOS_AUTHORIZED_DIRECTORIES_SETTINGS_NAMESPACE = "dsh-fnos-authorized-directories";
+/** Same-origin route that lists the directories currently authorized for the app. */
+declare const FNOS_AUTHORIZED_DIRECTORIES_PATH = "/plugins/dsh-fnos/authorized-directories";
+/** Same-origin route that removes one application directory ACL. */
+declare const FNOS_AUTHORIZED_DIRECTORIES_DELETE_PATH = "/plugins/dsh-fnos/authorized-directories/delete";
+/** Same-origin route that converts internal fnOS paths to readable paths. */
+declare const FNOS_PATH_CONVERSION_PATH = "/plugins/dsh-fnos/paths/convert";
+/** Same-origin route that validates a DSH path before fnOS opens it. */
+declare const FNOS_PATH_OPEN_VALIDATION_PATH = "/plugins/dsh-fnos/paths/open/validate";
+/** Same-origin route that lists one level below an authorized NAS directory. */
+declare const FNOS_AUTHORIZED_ENTRIES_PATH = "/plugins/dsh-fnos/authorized-directories/entries";
+interface ReadablePath {
+  /** Internal fnOS path used by the Host and DSH reference codec. */
+  path: string;
+  /** User-facing path returned by trim.file.convertPath. */
+  semanticPath: string;
+}
+type AuthorizedEntryKind = 'file' | 'directory';
+interface AuthorizedEntry {
+  /** Internal fnOS path used by DSH's reference codec. */
+  path: string;
+  /** User-facing path returned by trim.file.convertPath. */
+  semanticPath: string;
+  /** Whether the entry can be opened as a directory in the picker. */
+  kind: AuthorizedEntryKind;
+  /** Optional file size supplied by the Host for a lightweight listing. */
+  size?: number;
+  /** Optional modification timestamp in milliseconds. */
+  modifiedAt?: number;
+}
+interface AuthorizedEntriesResponse {
+  /** Directory represented by this listing; omitted for the authorized roots. */
+  directory?: ReadablePath;
+  entries: AuthorizedEntry[];
+  truncated?: boolean;
+}
+//#endregion
+//#region src/authorized-directories.d.ts
+/** fnOS supplies user-authorized application paths through this variable. */
+declare const FNOS_ACCESSIBLE_PATHS_ENV = "TRIM_DATA_ACCESSIBLE_PATHS";
+/** fnOS supplies the application's declared shared data paths through this variable. */
+declare const FNOS_DATA_SHARE_PATHS_ENV = "TRIM_DATA_SHARE_PATHS";
+interface UserAclResult {
+  /** Whether fnOS returned a usable ACL response for the current user. */
+  available: boolean;
+  /** Paths that fnOS says the current user can read. */
+  readable: Set<string>;
+}
+/** Injectable ACL checker used by the path validation tests. */
+type UserAclChecker = (req: IncomingMessage | undefined, paths: readonly string[]) => Promise<UserAclResult>;
+interface PathValidationOptions {
+  /** Override the application roots when validating in isolation. */
+  roots?: readonly string[];
+  /** Override the current-user ACL lookup when validating in isolation. */
+  checkUserAcl?: UserAclChecker;
+}
+type PathValidationFailure = 'fnos-path-not-authorized' | 'fnos-path-not-found' | 'fnos-path-not-readable' | 'fnos-user-permission-denied' | 'fnos-user-permission-unavailable';
+interface PathValidationResult {
+  ok: boolean;
+  failure?: PathValidationFailure;
+}
+/**
+ * Read the user identity supplied by the fnOS unified gateway.
+ *
+ * `TRIM_UID` is the application service user and must not be used here. The
+ * current browser user is carried by `X-Trim-Userid` on gateway requests.
+ */
+declare function gatewayUserId(req: IncomingMessage | undefined): number | undefined;
+/** Normalize one fnOS volume path for display and exact delete matching. */
+declare function normalizeAuthorizedPath(value: unknown): string | undefined;
+/** Normalize a path used for the open authorization boundary. */
+declare function normalizePathForAuthorization(value: unknown): string | undefined;
+/** Check a target path against authorized roots without confusing path prefixes. */
+declare function isPathWithinAuthorizedDirectory(pathValue: unknown, rootsValue: unknown): boolean;
+/** Keep API order while removing malformed and duplicate paths. */
+declare function normalizeAuthorizedPaths(value: unknown): string[];
+/** Parse a fnOS colon-separated path environment variable. */
+declare function splitPathEnvironment(value: unknown): string[];
+/** Read user-authorized paths from the lifecycle environment and de-duplicate them. */
+declare function accessiblePathsFromEnvironment(env?: NodeJS.ProcessEnv): string[];
+/** Read declared application data shares for display and de-duplicate them. */
+declare function dataSharePathsFromEnvironment(env?: NodeJS.ProcessEnv): string[];
+/** Combine path sources without changing the first-seen order. */
+declare function mergeAuthorizedPaths(...values: unknown[]): string[];
+/** Keep a just-removed ACL out of the process-local merged configuration. */
+declare function markAuthorizedPathRemoved(value: unknown): void;
+/** Pair internal paths with fnOS semantic paths, falling back per entry. */
+declare function convertPathsForDisplay(pathsValue: unknown, language?: string): Promise<ReadablePath[]>;
+/**
+ * Validate a DSH file/directory target using all applicable permission layers:
+ * the app's real shared roots, the process's actual fs access, and the
+ * current NAS user ACL supplied by the unified gateway.
+ */
+declare function validatePathForOpen(pathValue: unknown, req?: IncomingMessage, options?: PathValidationOptions): Promise<PathValidationResult>;
+/** Backward-compatible boolean helper for callers that only need a verdict. */
+declare function isAuthorizedPathForOpen(pathValue: unknown, req?: IncomingMessage): Promise<boolean>;
+/**
+ * List only existing, readable authorized roots or one authorized directory
+ * level. The app ACL root is only the first boundary: every returned entry is
+ * also checked with the real filesystem and, when the request came through
+ * the fnOS gateway, the current user's ACL.
+ */
+declare function loadAuthorizedEntries(req: IncomingMessage, pathValue?: string): Promise<AuthorizedEntriesResponse>;
+//#endregion
+//#region src/index.d.ts
+/** Stable Host bundle name. */
+declare const name = "@tnnevol/dsh-fnos";
+/** Settings back the fnOS card and the cached pre-plugin theme bootstrap. */
+declare const FnosSettingsSchema: z<Schemastery.ObjectS<{
+  systemTheme: z<"light" | "dark", "light" | "dark">;
+}>, Schemastery.ObjectT<{
+  systemTheme: z<"light" | "dark", "light" | "dark">;
+}>>;
+declare const FNOS_AUTHORIZED_DIRECTORIES_SETTINGS_NS: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+/** Host services required by the fnOS settings namespace and Web routes. */
+declare const inject: string[];
+declare function apply(ctx: Context): void;
+//#endregion
+export { FNOS_ACCESSIBLE_PATHS_ENV, FNOS_AUTHORIZED_DIRECTORIES_DELETE_PATH, FNOS_AUTHORIZED_DIRECTORIES_PATH, FNOS_AUTHORIZED_DIRECTORIES_SETTINGS_NAMESPACE, FNOS_AUTHORIZED_DIRECTORIES_SETTINGS_NS, FNOS_AUTHORIZED_ENTRIES_PATH, FNOS_DATA_SHARE_PATHS_ENV, FNOS_PATH_CONVERSION_PATH, FNOS_PATH_OPEN_VALIDATION_PATH, FnosSettingsSchema, accessiblePathsFromEnvironment, apply, convertPathsForDisplay, dataSharePathsFromEnvironment, gatewayUserId, inject, isAuthorizedPathForOpen, isPathWithinAuthorizedDirectory, loadAuthorizedEntries, markAuthorizedPathRemoved, mergeAuthorizedPaths, name, normalizeAuthorizedPath, normalizeAuthorizedPaths, normalizePathForAuthorization, splitPathEnvironment, validatePathForOpen };