@brftech/filex-core 0.19.0 → 0.20.0

package/src/types/Connections.ts

@@ -0,0 +1,122 @@
+/**
+ * Connections — the shapes the storage-connection surface works with.
+ *
+ * Every one of these mirrors something the BACKEND declares, on purpose.
+ * `StorageField` / `StorageDriverDescriptor` are the wire form of
+ * `backend/internal/storage/descriptor.go`, served by
+ * `GET /api/admin/storage-drivers`: a driver states its own config keys,
+ * their types, which one is the storage root and which hold credentials,
+ * and every surface renders that one declaration.
+ *
+ * The alternative — a form per surface — is exactly what shipped broken:
+ * three of the four drivers the admin UI offered could not be created
+ * through it because the form collected keys the backend never read. A
+ * second hand-written form in the desktop app would have been a fourth
+ * copy of the same mistake.
+ */
+
+export type StorageFieldType = 'string' | 'int' | 'bool' | 'password' | 'select';
+
+export interface StorageFieldOption {
+  value: string;
+  /** English fallback; `i18n_key` wins when the catalogue has it. */
+  label: string;
+  i18n_key?: string;
+}
+
+/** One config key of a storage driver, as declared by the driver itself. */
+export interface StorageField {
+  key: string;
+  type: StorageFieldType;
+  /** English fallback label — used only when `i18n_key` is missing from
+   *  the catalogue, so a driver released after this build still renders
+   *  readable labels instead of raw keys. */
+  label: string;
+  help?: string;
+  i18n_key: string;
+  help_i18n_key?: string;
+  required: boolean;
+  /** Credential material: render masked, never log, never put in a URL. */
+  secret: boolean;
+  default?: unknown;
+  placeholder?: string;
+  options?: StorageFieldOption[];
+  min?: number;
+  max?: number;
+  monospace?: boolean;
+  multiline?: boolean;
+  advanced?: boolean;
+  /** THE field that scopes the storage inside the backend (s3 prefix,
+   *  local path, sftp/ftp/webdav root). The backend rejects an empty or
+   *  "/" value with ROOT_PATH_FORBIDDEN. */
+  root?: boolean;
+  /** Legacy spellings the driver still reads for this field. */
+  aliases?: string[];
+}
+
+export interface StorageDriverCapabilities {
+  read?: boolean;
+  write?: boolean;
+  move?: boolean;
+  copy?: boolean;
+  delete?: boolean;
+  mkdir?: boolean;
+  presign?: boolean;
+  watch?: boolean;
+}
+
+export interface StorageDriverDescriptor {
+  driver: string;
+  label: string;
+  i18n_key: string;
+  fields: StorageField[];
+  capabilities: StorageDriverCapabilities;
+}
+
+/** A configured storage, as `GET /api/admin/storages` returns it. */
+export interface StorageRow {
+  id: number;
+  name: string;
+  driver: string;
+  enabled: boolean;
+  read_only: boolean;
+  config: Record<string, unknown>;
+  rbac_enabled?: boolean;
+  sync_mode?: string;
+  created_at?: string;
+  updated_at?: string;
+  stats?: { file_count?: number; total_size_bytes?: number };
+}
+
+/** POST/PATCH body for a storage. */
+export interface StorageWrite {
+  name: string;
+  driver: string;
+  config: Record<string, unknown>;
+  read_only?: boolean;
+  enabled?: boolean;
+}
+
+export interface StorageTestResult {
+  ok: boolean;
+  error?: string;
+  object_count?: number;
+  sample_listing?: unknown[];
+}
+
+/** The signed-in account, from `GET /api/auth/me`. */
+export interface ConnectionsUser {
+  id: number;
+  email: string;
+  display_name?: string;
+  role?: string;
+}
+
+/**
+ * Why the caller cannot manage storages, when they cannot.
+ *
+ * `none` is the honest answer for a signed-in non-admin: the surface then
+ * shows the connection guides (which every user needs) and a plain "ask
+ * your administrator" line instead of a form that would 403 on submit.
+ */
+export type ManageDenial = 'none' | 'anonymous' | 'unreachable';

package/src/types/ExplorerConfig.ts

@@ -47,6 +47,15 @@ export type LocaleCode = 'tr' | 'en';
  */
 export interface EndpointMap {
   manager: string;
+  /**
+   * Staged upload — the chunked, resumable, driver-agnostic path every client
+   * speaks (docs/UPLOADS.md). The per-upload routes (`PUT/GET/DELETE {id}`,
+   * `POST {id}/commit`) are derived from it by stripping `/begin`, so one
+   * override moves the whole protocol.
+   */
+  uploadBegin: string | null;
+  /** Legacy S3-presigned chunked upload. Still served by the backend for
+   *  older embedders; nothing in this package calls it. */
   uploadInit: string | null;
   uploadFinalize: string | null;
   uploadAbort: string | null;
@@ -83,6 +92,8 @@ export interface ExplorerConfig {
   endpoint?: string;
 
   // ——— Per-route overrides (optional; auto-derived from apiBase if absent) ———
+  /** Staged upload entry point; the `{id}` routes hang off it. */
+  uploadBegin?: string;
   uploadInit?: string;
   uploadFinalize?: string;
   uploadAbort?: string;
@@ -198,10 +209,20 @@ export interface ExplorerConfig {
    */
   viewerBaseUrl?: string;
 
-  /** Upload chunk size (bytes). Default 5 MB. */
+  /**
+   * Upload chunk size (bytes). Default 8 MB — the server's default too, so
+   * "large enough to chunk" means the same thing on both ends. The value the
+   * server returns from `begin` is binding; this is what the client asks for
+   * and the threshold above which a file goes on the staged path at all.
+   */
   chunkSize?: number;
 
-  /** Parallel chunks. Default 4. */
+  /**
+   * @deprecated Ignored since the move to the staged protocol. Chunks are sent
+   * sequentially because `offset` — the resume point — is the contiguous run
+   * from part 1; parallel parts would leave holes that a resumed upload has to
+   * re-send anyway.
+   */
   parallelChunks?: number;
 
   /** Theme. */

package/src/types/NFSExports.ts

@@ -0,0 +1,47 @@
+/**
+ * NFS exports, as the frontend sees them.
+ *
+ * ⚠⚠ The `path` a freshly minted export returns IS the credential. NFSv3 cannot
+ * authenticate a request without Kerberos, so filex binds the identity to the
+ * export path instead: 32 bytes of entropy, shown once, stored hashed. Whoever
+ * knows it can mount as that account — which is why it belongs in a config file
+ * treated like a password, and why the UI has to say so rather than letting
+ * somebody discover it from a mount table.
+ */
+
+export interface NFSExport {
+  id: number;
+  user_id: number;
+  api_token_id?: number | null;
+  label: string;
+  /** Confinement, in the same shape the S3 keys use. */
+  storage_name?: string;
+  prefix?: string;
+  /** Refuses every write through this mount, whatever the account may do. */
+  read_only: boolean;
+  /** Comma-separated CIDR allow-list. Empty = any address the listener takes. */
+  allow_cidrs?: string;
+  created_at: string;
+  last_used_at?: string | null;
+  expires_at?: string | null;
+  disabled_at?: string | null;
+}
+
+/** Where an NFS client should point, reported by the server. */
+export interface NFSConnection {
+  /** The FILEX_NFS kill switch. */
+  enabled: boolean;
+  host: string;
+  /**
+   * ⚠ 2049 by convention, but filex serves mount AND nfs on this one port and
+   * runs no portmapper — so a client needs `port=` and `mountport=` both set to
+   * it. A guide that omitted either produces a mount that hangs.
+   */
+  port: number;
+}
+
+/** What minting returns. The path appears exactly once. */
+export interface NFSExportCreated extends NFSConnection {
+  export: NFSExport;
+  path: string;
+}

package/src/types/S3Keys.ts

@@ -0,0 +1,55 @@
+/**
+ * The S3 access-key surface, as the frontend sees it.
+ *
+ * Mirrors `model.S3AccessKey` and the connection facts the key endpoints
+ * return alongside it. The facts travel WITH the keys on purpose: a key
+ * without an endpoint is not a usable credential, and a UI that assembled
+ * the URL itself would be a second place to get it wrong (the application
+ * URL and the S3 endpoint are different hosts whenever one is configured).
+ */
+
+export interface S3AccessKey {
+  id: number;
+  access_key_id: string;
+  user_id: number;
+  api_token_id?: number | null;
+  label: string;
+  /** Optional confinement, in the shape S3 clients already understand. */
+  bucket?: string;
+  prefix?: string;
+  created_at: string;
+  last_used_at?: string | null;
+  expires_at?: string | null;
+  /** Set = the key is switched off but still in the audit trail. */
+  disabled_at?: string | null;
+}
+
+/** Where to point a client, and how to address it. */
+export interface S3Connection {
+  /** Absolute endpoint URL — the S3 host's root, or `<app>/s3`. */
+  endpoint: string;
+  /** The FILEX_S3 kill switch. False = the operator turned the endpoint off. */
+  enabled: boolean;
+  /**
+   * True when there is no dedicated host, so clients must be told to force
+   * path-style addressing. A current SDK defaults to virtual-hosted and then
+   * fails at DNS with an error that names neither filex nor the cause.
+   */
+  path_style: boolean;
+}
+
+/** What a freshly minted key returns. The secret appears exactly once. */
+export interface S3KeyCreated extends S3Connection {
+  key: S3AccessKey;
+  secret: string;
+}
+
+/** What the caller asked for when minting. */
+export interface S3KeyRequest {
+  label: string;
+  /** Mint FROM an API token, inheriting its scopes, confinement and expiry. */
+  api_token_id?: number;
+  bucket?: string;
+  prefix?: string;
+  expires_at?: string;
+}

package/src/types/SSHKeys.ts

@@ -0,0 +1,54 @@
+/**
+ * The SSH key surface, as the frontend sees it.
+ *
+ * Mirrors `model.SSHPublicKey` plus the connection facts the endpoint returns
+ * with it — the host, the port and the LOGIN NAME, which is the piece people
+ * most often get wrong when they type it themselves.
+ */
+
+export interface SSHPublicKey {
+  id: number;
+  user_id: number;
+  name: string;
+  /** SHA256 fingerprint, base64, without the `SHA256:` prefix. */
+  fingerprint: string;
+  /** The normalised wire form, `<type> <base64>`. */
+  public_key: string;
+  created_at: string;
+  last_used_at?: string | null;
+  /** Set = the key is switched off but still listed. */
+  disabled_at?: string | null;
+}
+
+/** Where an SSH client should connect, and as whom. */
+export interface SSHConnection {
+  /** The FILEX_SFTP kill switch. False = the operator turned the port off. */
+  enabled: boolean;
+  host: string;
+  /**
+   * ⚠ Not 22 and not the web port. SFTP is raw TCP on a port of its own, and
+   * a guide that printed 443 would send every client at a proxy that speaks
+   * only HTTP.
+   */
+  port: number;
+  /** The login name: the account's username, or its e-mail when it has none. */
+  login: string;
+  /** The FTPS endpoint, reported by the same call. */
+  ftps?: FTPSFacts;
+}
+
+/** What an FTP client needs to be told, computed on the server. */
+export interface FTPSFacts {
+  enabled: boolean;
+  host: string;
+  port: number;
+  /**
+   * ⚠ The passive data-port range. A firewall that blocks it makes every
+   * transfer HANG with no error on either side — the classic FTP failure, and
+   * impossible to diagnose from the client end. It belongs in the guide.
+   */
+  pasv_min: number;
+  pasv_max: number;
+  /** True when no certificate was configured and the server generated one. */
+  self_signed: boolean;
+}

package/src/types/Tokens.ts

@@ -0,0 +1,39 @@
+/**
+ * The self-service API-token surface (`/api/tokens`).
+ *
+ * ⚠ Why this exists at all: three of the six protocols filex serves take an
+ * API token as their password — FTPS, WebDAV and `filex mount`. Until
+ * 2026-08-17 the only place to mint one was `/api/admin/ai-tokens`, which is
+ * admin-only, so a normal user opened the FTPS guide, read "use an API token
+ * as the password", and had nowhere to get one. The backend route has always
+ * been open to every account; only the UI was missing.
+ */
+
+/** One token row. The secret is NEVER in here — only the hash is stored. */
+export interface ApiToken {
+  id: number;
+  label: string;
+  scopes: string;
+  /** Per-token display identities for the audit trail; may be absent. */
+  usernames?: string | null;
+  created_at?: string;
+  last_used_at?: string | null;
+  expires_at?: string | null;
+}
+
+/** What comes back from a mint. `token` is shown exactly once. */
+export interface ApiTokenCreated {
+  token: string;
+  row: ApiToken;
+}
+
+export interface ApiTokenRequest {
+  label: string;
+  /**
+   * Comma-separated verbs. The server CAPS this against the caller's role and
+   * their own grants, so asking for more than you have is refused rather than
+   * quietly granted — never send `admin`, it is rejected outright here.
+   */
+  scopes?: string;
+  expires_in_days?: number;
+}