BlueGit

timfa filemanager

Merge branch 'ada/sync-api' into 'master'

timfa

Authored 2026-10-24 · 3 weeks ago

Hash
13e7590c81ce95b99a5bf97e790489cecd19c22f
Pipeline
Passed
14 files changed +4261 −2
.github/tests.md +22 −2
@@ -19,6 +19,16 @@
19 19
20 20 ---
21 21
22 ## `test/api.v1.test.js`
23 - `OAuth authorization code + PKCE`
24 - `Access management (web session)`
25 - `Scopes and isolation`
26 - `Files: upload, download, conflicts`
27 - `Resumable uploads`
28 - `Delta feed`
29
30 ---
31
22 32 ## `test/auth.routes.test.js`
23 33 - `GET /api/auth/server-key`
24 34 - `GET /api/auth/setup-needed`
@@ -41,11 +51,17 @@
41 51
42 52 ---
43 53
54 ## `test/file-hash-queue.test.js`
55 - `file hash queue`
56
57 ---
58
44 59 ## `test/files.routes.test.js`
45 60 - `POST /api/files/upload`
46 61 - `POST /api/files/move`
47 62 - `root alias endpoints`
48 63 - `last visited folder persistence`
64 - `GET /api/files/preview-image`
49 65 - `GET /api/files/thumbnail`
50 66 - `GET /api/files/root-access`
51 67 - `orphaned user folder access`
@@ -72,6 +88,11 @@
72 88
73 89 ---
74 90
91 ## `test/search-index.test.js`
92 - `search index`
93
94 ---
95
75 96 ## `test/share.page.load.test.js`
76 97 - `share page video preview`
77 98
@@ -91,8 +112,6 @@
91 112
92 113 ## `test/shared-video-player.test.js`
93 114 - `shared image subtitle prefetching`
94 - `retries saved image subtitle selection when metadata arrives before player ready runs`
95 - `keeps image subtitles off when off was the saved preference`
96 115
97 116 ---
98 117
@@ -108,5 +127,6 @@
108 127
109 128 ## `test/video-stream.test.js`
110 129 - `video stream bootstrap`
130 - `text subtitle editor-note sanitization`
111 131
112 132 ---
@@ -19,6 +19,16 @@
19
19
20---
20---
21
21
22## `test/api.v1.test.js`
23- `OAuth authorization code + PKCE`
24- `Access management (web session)`
25- `Scopes and isolation`
26- `Files: upload, download, conflicts`
27- `Resumable uploads`
28- `Delta feed`
29
30---
31
22## `test/auth.routes.test.js`
32## `test/auth.routes.test.js`
23- `GET /api/auth/server-key`
33- `GET /api/auth/server-key`
24- `GET /api/auth/setup-needed`
34- `GET /api/auth/setup-needed`
@@ -41,11 +51,17 @@
41
51
42---
52---
43
53
54## `test/file-hash-queue.test.js`
55- `file hash queue`
56
57---
58
44## `test/files.routes.test.js`
59## `test/files.routes.test.js`
45- `POST /api/files/upload`
60- `POST /api/files/upload`
46- `POST /api/files/move`
61- `POST /api/files/move`
47- `root alias endpoints`
62- `root alias endpoints`
48- `last visited folder persistence`
63- `last visited folder persistence`
64- `GET /api/files/preview-image`
49- `GET /api/files/thumbnail`
65- `GET /api/files/thumbnail`
50- `GET /api/files/root-access`
66- `GET /api/files/root-access`
51- `orphaned user folder access`
67- `orphaned user folder access`
@@ -72,6 +88,11 @@
72
88
73---
89---
74
90
91## `test/search-index.test.js`
92- `search index`
93
94---
95
75## `test/share.page.load.test.js`
96## `test/share.page.load.test.js`
76- `share page video preview`
97- `share page video preview`
77
98
@@ -91,8 +112,6 @@
91
112
92## `test/shared-video-player.test.js`
113## `test/shared-video-player.test.js`
93- `shared image subtitle prefetching`
114- `shared image subtitle prefetching`
94- `retries saved image subtitle selection when metadata arrives before player ready runs`
95- `keeps image subtitles off when off was the saved preference`
96
115
97---
116---
98
117
@@ -108,5 +127,6 @@
108
127
109## `test/video-stream.test.js`
128## `test/video-stream.test.js`
110- `video stream bootstrap`
129- `video stream bootstrap`
130- `text subtitle editor-note sanitization`
111
131
112---
132---
.gitignore +1 −0
@@ -10,3 +10,4 @@ zip-cache/
10 10 logs.txt
11 11
12 12 *.db-journal
13 api-uploads/
@@ -10,3 +10,4 @@ zip-cache/
10logs.txt
10logs.txt
11
11
12*.db-journal
12*.db-journal
13api-uploads/
docs/api.md added +210 −0
@@ -0,0 +1,210 @@
1 # Filemanager sync API (v1)
2
3 This API is for apps that sync files with the file manager: phone apps,
4 desktop sync clients, or background services. It covers login with user
5 consent, listing, a change feed (delta), upload (including resumable
6 uploads for large files), download with Range, folders, move, delete and
7 conflict detection.
8
9 - Machine-readable spec: [`docs/openapi.json`](openapi.json). A running
10 server also serves it at `/api/v1/openapi.json`.
11 - OAuth metadata: `/.well-known/oauth-authorization-server`.
12 - Users manage access on **`/apps.html`** ("Connected apps"). There they
13 can see every authorised app, device and token, see when each was last
14 used, revoke them, and create personal tokens.
15
16 A token can never see more than its user can. Every request goes through
17 the same permission checks as the web UI: per-root read/write rights,
18 the user's own folder, and admin rights.
19
20 ## 1. Register your app (once)
21
22 An admin registers the app on `/apps.html` under "OAuth clients". You
23 provide a name and one or more redirect URIs and get back a `client_id`
24 (`fmc_...`). Clients are **public**: there is no client secret, and PKCE
25 is mandatory.
26
27 These redirect URIs are allowed:
28
29 | Kind | Example | Notes |
30 |---|---|---|
31 | HTTPS | `https://sync.example.com/callback` | Web services |
32 | Loopback | `http://127.0.0.1/callback` | Desktop apps. Any port is accepted at runtime (RFC 8252) |
33 | Private scheme | `com.example.sync:/callback` | Mobile apps |
34
35 ## 2. Authorisation (authorization code + PKCE)
36
37 1. Generate a `code_verifier`: 43–128 characters from `A-Z a-z 0-9 - . _ ~`.
38 Then compute `code_challenge = BASE64URL(SHA256(code_verifier))`.
39 2. Open the following URL in the system browser:
40
41 ```
42 GET /oauth/authorize?response_type=code
43 &client_id=fmc_...
44 &redirect_uri=com.example.sync:/callback
45 &scope=files:read%20files:write
46 &state=<random>
47 &code_challenge=<challenge>&code_challenge_method=S256
48 &device_name=Tim's%20Pixel
49 ```
50
51 The user sees which app, which device and which permissions are
52 requested. They sign in and click **Allow** or **Deny**.
53 3. The browser is redirected to `redirect_uri?code=...&state=...&iss=...`.
54 Check that `state` matches the value you sent. The code is valid for
55 10 minutes and works only once. If the user denied access, you get
56 `error=access_denied` instead.
57 4. Exchange the code for tokens:
58
59 ```
60 POST /oauth/token (application/x-www-form-urlencoded or JSON)
61 grant_type=authorization_code&client_id=fmc_...&code=...
62 &redirect_uri=com.example.sync:/callback&code_verifier=...
63 ```
64
65 ```json
66 {"access_token":"fma_...","token_type":"Bearer","expires_in":3600,
67 "refresh_token":"fmr_...","scope":"files:read files:write","grant_id":"g_..."}
68 ```
69
70 5. Send `Authorization: Bearer <access_token>` on every API call. An
71 access token is valid for 1 hour. Renew it with
72 `grant_type=refresh_token&client_id=...&refresh_token=...`.
73 **Refresh tokens rotate**: always store the new one. If an old refresh
74 token is used again, the whole grant is revoked, because that points to
75 a stolen token. A refresh token expires after 90 days without use.
76 6. Logout: `POST /oauth/revoke` with `token=<refresh or access token>`.
77
78 Each authorisation is a separate grant, so each device has its own
79 tokens, and the user can revoke one device without affecting the others.
80
81 **Scopes:** `files:read` lets an app list, read, download and use the
82 delta feed. `files:write` lets it upload, create folders, move and delete,
83 and always includes `files:read`.
84
85 **Personal tokens** (`fmp_...`) for your own scripts are created on
86 `/apps.html`. They are used the same way (`Authorization: Bearer`), can
87 optionally expire, and can be revoked there.
88
89 ## 3. Paths and roots
90
91 `GET /api/v1/roots` returns the roots the user can see. `~` is always the
92 user's own folder. Other roots are the shared folders the user has rights
93 to. All paths are virtual and have the form `/<root-id>/<relative path>`,
94 for example `/~/Photos/2024/a.jpg` or `/team/report.pdf`. The segments
95 `..` and `.`, backslashes and symlinks that leave the root are refused,
96 and symlinks are not listed.
97
98 Every file or folder (`Entry`) has the following fields:
99
100 | Field | Meaning |
101 |---|---|
102 | `id` | Stable identity. It stays the same across renames and moves on the same disk |
103 | `path`, `name`, `type` | `type` is `file` or `folder` |
104 | `size`, `mtime`, `mtime_ms` | Size and modification time |
105 | `version` | Opaque. It changes on every change and is also the `ETag` |
106 | `sha256` | Present when known. Use `GET /files/metadata?path=..&hash=1` to have it computed |
107
108 ## 4. Sync walkthrough
109
110 ```text
111 # First sync of a root
112 GET /api/v1/delta?root=~ -> reset=true, entries(change=exists), cursor, has_more
113 GET /api/v1/delta?root=~&cursor=<c> -> repeat while has_more
114 store cursor
115
116 # Every time after that (poll, e.g. every 30-60 s or when the app comes to the foreground)
117 GET /api/v1/delta?root=~&cursor=<c>
118 created -> download (GET /files/content)
119 modified -> download if version differs from your local copy
120 moved -> rename locally old_path -> path (children are implied)
121 deleted -> delete locally (folders: including contents)
122 repeat while has_more, then store the new cursor
123 410 cursor_expired -> start over without a cursor and reconcile with local state
124 ```
125
126 The feed sees all changes: those made through the API, through the web
127 UI, and directly on disk. Changes from outside the API become visible
128 within about 15 seconds (`api.scanIntervalSeconds`). Changes made through
129 the API show up right away.
130
131 Pushing local changes:
132
133 ```text
134 new file : PUT /files/content?path=/~/a.txt&mtime=<ms> + If-None-Match: *
135 changed : PUT /files/content?path=/~/a.txt + If-Match: "<version you last saw>"
136 large file : POST /uploads {path,size,sha256,mtime,if_match|if_none_match}
137 PATCH /uploads/<id> (Upload-Offset: n, body = chunk <= max_chunk_bytes) ...
138 on interruption: GET /uploads/<id> -> offset, resume from there
139 POST /uploads/<id>/complete
140 rename/move: POST /files/move {from,to,if_match}
141 delete : DELETE /files?path=..&recursive=true + If-Match
142 folder : POST /folders {path, parents:true, exist_ok:true}
143 ```
144
145 **Conflicts:** a write never overwrites anything silently.
146
147 - `412 precondition_failed`: the version no longer matches `If-Match`, or
148 the target already exists while you sent `If-None-Match: *`.
149 - `409 conflict`: the target exists and you sent no `If-Match`.
150
151 Both responses include `current`, the server's state. The usual approach
152 is to save your local copy under a new name, such as
153 `a (conflict from Pixel).txt`, and then download the server version.
154 `overwrite=true` replaces the target on purpose.
155
156 Uploads first go to a temporary file. They only become visible after
157 the size and SHA-256 are verified, with an atomic rename. That way other
158 clients never see a half-written file.
159
160 **Download:** `GET /files/content?path=..` supports `Range`/`If-Range`,
161 which lets an app resume a download, and `If-None-Match`, which returns
162 304. The `ETag` is the `version`.
163
164 **Delete is permanent.** The file manager has no trash, so ask the user
165 for confirmation before you delete.
166
167 ## 5. Errors and limits
168
169 Errors are always JSON: `{"error": "<code>", "message": "..."}`.
170
171 | Status | Codes |
172 |---|---|
173 | 400 | `invalid_path`, `invalid_request`, `invalid_cursor`, `not_a_folder`, `not_a_file` |
174 | 401 | `invalid_token` |
175 | 403 | `insufficient_scope`, `forbidden` |
176 | 404 | `not_found`. Also returned for paths you are not allowed to see |
177 | 409 | `conflict`, `parent_missing`, `folder_not_empty`, `offset_mismatch`, `incomplete` |
178 | 410 | `cursor_expired` |
179 | 412 | `precondition_failed` |
180 | 413 | `too_large` |
181 | 422 | `checksum_mismatch` |
182 | 429 | `too_many_uploads` |
183 | 507 | `quota_exceeded`, `too_many_entries` |
184
185 The limits are in `GET /api/v1/me` and can be set in `config.json` under
186 `"api"`:
187
188 | Key | Default |
189 |---|---|
190 | `maxUploadBytes` | 10 GB |
191 | `maxChunkBytes` | 64 MB |
192 | `maxOpenUploadsPerUser` | 20 |
193 | `uploadTtlHours` | 24 |
194 | `maxHashBytes` | 4 GB |
195 | `scanIntervalSeconds` | 15 |
196 | `maxSyncEntries` | 500000 |
197 | `uploadDir` | `<app>/api-uploads` |
198
199 The personal-folder quota (`userFolderSizeLimit`) also applies to the
200 API. The change history is kept for 30 days.
201
202 ## 6. Example (curl, personal token)
203
204 ```bash
205 T=fmp_...; H="Authorization: Bearer $T"; S=https://files.example.com/api/v1
206 curl -H "$H" $S/roots
207 curl -H "$H" -T notes.txt -H 'If-None-Match: *' "$S/files/content?path=/~/notes.txt"
208 curl -H "$H" "$S/files/content?path=/~/notes.txt" -o notes.txt
209 curl -H "$H" "$S/delta?root=~"
210 ```
@@ -0,0 +1,210 @@
1# Filemanager sync API (v1)
2
3This API is for apps that sync files with the file manager: phone apps,
4desktop sync clients, or background services. It covers login with user
5consent, listing, a change feed (delta), upload (including resumable
6uploads for large files), download with Range, folders, move, delete and
7conflict detection.
8
9- Machine-readable spec: [`docs/openapi.json`](openapi.json). A running
10 server also serves it at `/api/v1/openapi.json`.
11- OAuth metadata: `/.well-known/oauth-authorization-server`.
12- Users manage access on **`/apps.html`** ("Connected apps"). There they
13 can see every authorised app, device and token, see when each was last
14 used, revoke them, and create personal tokens.
15
16A token can never see more than its user can. Every request goes through
17the same permission checks as the web UI: per-root read/write rights,
18the user's own folder, and admin rights.
19
20## 1. Register your app (once)
21
22An admin registers the app on `/apps.html` under "OAuth clients". You
23provide a name and one or more redirect URIs and get back a `client_id`
24(`fmc_...`). Clients are **public**: there is no client secret, and PKCE
25is mandatory.
26
27These redirect URIs are allowed:
28
29| Kind | Example | Notes |
30|---|---|---|
31| HTTPS | `https://sync.example.com/callback` | Web services |
32| Loopback | `http://127.0.0.1/callback` | Desktop apps. Any port is accepted at runtime (RFC 8252) |
33| Private scheme | `com.example.sync:/callback` | Mobile apps |
34
35## 2. Authorisation (authorization code + PKCE)
36
371. Generate a `code_verifier`: 43–128 characters from `A-Z a-z 0-9 - . _ ~`.
38 Then compute `code_challenge = BASE64URL(SHA256(code_verifier))`.
392. Open the following URL in the system browser:
40
41 ```
42 GET /oauth/authorize?response_type=code
43 &client_id=fmc_...
44 &redirect_uri=com.example.sync:/callback
45 &scope=files:read%20files:write
46 &state=<random>
47 &code_challenge=<challenge>&code_challenge_method=S256
48 &device_name=Tim's%20Pixel
49 ```
50
51 The user sees which app, which device and which permissions are
52 requested. They sign in and click **Allow** or **Deny**.
533. The browser is redirected to `redirect_uri?code=...&state=...&iss=...`.
54 Check that `state` matches the value you sent. The code is valid for
55 10 minutes and works only once. If the user denied access, you get
56 `error=access_denied` instead.
574. Exchange the code for tokens:
58
59 ```
60 POST /oauth/token (application/x-www-form-urlencoded or JSON)
61 grant_type=authorization_code&client_id=fmc_...&code=...
62 &redirect_uri=com.example.sync:/callback&code_verifier=...
63 ```
64
65 ```json
66 {"access_token":"fma_...","token_type":"Bearer","expires_in":3600,
67 "refresh_token":"fmr_...","scope":"files:read files:write","grant_id":"g_..."}
68 ```
69
705. Send `Authorization: Bearer <access_token>` on every API call. An
71 access token is valid for 1 hour. Renew it with
72 `grant_type=refresh_token&client_id=...&refresh_token=...`.
73 **Refresh tokens rotate**: always store the new one. If an old refresh
74 token is used again, the whole grant is revoked, because that points to
75 a stolen token. A refresh token expires after 90 days without use.
766. Logout: `POST /oauth/revoke` with `token=<refresh or access token>`.
77
78Each authorisation is a separate grant, so each device has its own
79tokens, and the user can revoke one device without affecting the others.
80
81**Scopes:** `files:read` lets an app list, read, download and use the
82delta feed. `files:write` lets it upload, create folders, move and delete,
83and always includes `files:read`.
84
85**Personal tokens** (`fmp_...`) for your own scripts are created on
86`/apps.html`. They are used the same way (`Authorization: Bearer`), can
87optionally expire, and can be revoked there.
88
89## 3. Paths and roots
90
91`GET /api/v1/roots` returns the roots the user can see. `~` is always the
92user's own folder. Other roots are the shared folders the user has rights
93to. All paths are virtual and have the form `/<root-id>/<relative path>`,
94for example `/~/Photos/2024/a.jpg` or `/team/report.pdf`. The segments
95`..` and `.`, backslashes and symlinks that leave the root are refused,
96and symlinks are not listed.
97
98Every file or folder (`Entry`) has the following fields:
99
100| Field | Meaning |
101|---|---|
102| `id` | Stable identity. It stays the same across renames and moves on the same disk |
103| `path`, `name`, `type` | `type` is `file` or `folder` |
104| `size`, `mtime`, `mtime_ms` | Size and modification time |
105| `version` | Opaque. It changes on every change and is also the `ETag` |
106| `sha256` | Present when known. Use `GET /files/metadata?path=..&hash=1` to have it computed |
107
108## 4. Sync walkthrough
109
110```text
111# First sync of a root
112GET /api/v1/delta?root=~ -> reset=true, entries(change=exists), cursor, has_more
113GET /api/v1/delta?root=~&cursor=<c> -> repeat while has_more
114store cursor
115
116# Every time after that (poll, e.g. every 30-60 s or when the app comes to the foreground)
117GET /api/v1/delta?root=~&cursor=<c>
118 created -> download (GET /files/content)
119 modified -> download if version differs from your local copy
120 moved -> rename locally old_path -> path (children are implied)
121 deleted -> delete locally (folders: including contents)
122 repeat while has_more, then store the new cursor
123410 cursor_expired -> start over without a cursor and reconcile with local state
124```
125
126The feed sees all changes: those made through the API, through the web
127UI, and directly on disk. Changes from outside the API become visible
128within about 15 seconds (`api.scanIntervalSeconds`). Changes made through
129the API show up right away.
130
131Pushing local changes:
132
133```text
134new file : PUT /files/content?path=/~/a.txt&mtime=<ms> + If-None-Match: *
135changed : PUT /files/content?path=/~/a.txt + If-Match: "<version you last saw>"
136large file : POST /uploads {path,size,sha256,mtime,if_match|if_none_match}
137 PATCH /uploads/<id> (Upload-Offset: n, body = chunk <= max_chunk_bytes) ...
138 on interruption: GET /uploads/<id> -> offset, resume from there
139 POST /uploads/<id>/complete
140rename/move: POST /files/move {from,to,if_match}
141delete : DELETE /files?path=..&recursive=true + If-Match
142folder : POST /folders {path, parents:true, exist_ok:true}
143```
144
145**Conflicts:** a write never overwrites anything silently.
146
147- `412 precondition_failed`: the version no longer matches `If-Match`, or
148 the target already exists while you sent `If-None-Match: *`.
149- `409 conflict`: the target exists and you sent no `If-Match`.
150
151Both responses include `current`, the server's state. The usual approach
152is to save your local copy under a new name, such as
153`a (conflict from Pixel).txt`, and then download the server version.
154`overwrite=true` replaces the target on purpose.
155
156Uploads first go to a temporary file. They only become visible after
157the size and SHA-256 are verified, with an atomic rename. That way other
158clients never see a half-written file.
159
160**Download:** `GET /files/content?path=..` supports `Range`/`If-Range`,
161which lets an app resume a download, and `If-None-Match`, which returns
162304. The `ETag` is the `version`.
163
164**Delete is permanent.** The file manager has no trash, so ask the user
165for confirmation before you delete.
166
167## 5. Errors and limits
168
169Errors are always JSON: `{"error": "<code>", "message": "..."}`.
170
171| Status | Codes |
172|---|---|
173| 400 | `invalid_path`, `invalid_request`, `invalid_cursor`, `not_a_folder`, `not_a_file` |
174| 401 | `invalid_token` |
175| 403 | `insufficient_scope`, `forbidden` |
176| 404 | `not_found`. Also returned for paths you are not allowed to see |
177| 409 | `conflict`, `parent_missing`, `folder_not_empty`, `offset_mismatch`, `incomplete` |
178| 410 | `cursor_expired` |
179| 412 | `precondition_failed` |
180| 413 | `too_large` |
181| 422 | `checksum_mismatch` |
182| 429 | `too_many_uploads` |
183| 507 | `quota_exceeded`, `too_many_entries` |
184
185The limits are in `GET /api/v1/me` and can be set in `config.json` under
186`"api"`:
187
188| Key | Default |
189|---|---|
190| `maxUploadBytes` | 10 GB |
191| `maxChunkBytes` | 64 MB |
192| `maxOpenUploadsPerUser` | 20 |
193| `uploadTtlHours` | 24 |
194| `maxHashBytes` | 4 GB |
195| `scanIntervalSeconds` | 15 |
196| `maxSyncEntries` | 500000 |
197| `uploadDir` | `<app>/api-uploads` |
198
199The personal-folder quota (`userFolderSizeLimit`) also applies to the
200API. The change history is kept for 30 days.
201
202## 6. Example (curl, personal token)
203
204```bash
205T=fmp_...; H="Authorization: Bearer $T"; S=https://files.example.com/api/v1
206curl -H "$H" $S/roots
207curl -H "$H" -T notes.txt -H 'If-None-Match: *' "$S/files/content?path=/~/notes.txt"
208curl -H "$H" "$S/files/content?path=/~/notes.txt" -o notes.txt
209curl -H "$H" "$S/delta?root=~"
210```
docs/openapi.json added +1078 −0
@@ -0,0 +1,1078 @@
1 {
2 "openapi": "3.0.3",
3 "info": {
4 "title": "Filemanager sync API",
5 "version": "1.0.0",
6 "description": "Versioned API for sync clients (phone, desktop, services). See docs/api.md for the OAuth flow and a sync walkthrough. A token can never see or change more than its user can in the web UI."
7 },
8 "servers": [
9 {
10 "url": "/api/v1"
11 }
12 ],
13 "components": {
14 "securitySchemes": {
15 "oauth2": {
16 "type": "oauth2",
17 "description": "Authorization code with PKCE (S256), public clients without secret.",
18 "flows": {
19 "authorizationCode": {
20 "authorizationUrl": "/oauth/authorize",
21 "tokenUrl": "/oauth/token",
22 "refreshUrl": "/oauth/token",
23 "scopes": {
24 "files:read": "Read and download files",
25 "files:write": "Upload, create, move and delete (implies files:read)"
26 }
27 }
28 }
29 },
30 "personalToken": {
31 "type": "http",
32 "scheme": "bearer",
33 "description": "Personal access token (fmp_...) created on /apps.html"
34 }
35 },
36 "schemas": {
37 "Error": {
38 "type": "object",
39 "required": [
40 "error",
41 "message"
42 ],
43 "properties": {
44 "error": {
45 "type": "string",
46 "example": "conflict"
47 },
48 "message": {
49 "type": "string"
50 },
51 "current": {
52 "allOf": [
53 {
54 "$ref": "#/components/schemas/Entry"
55 }
56 ],
57 "nullable": true,
58 "description": "Current state of the target on 409/412"
59 },
60 "offset": {
61 "type": "integer",
62 "description": "Server offset on upload offset errors"
63 }
64 }
65 },
66 "Entry": {
67 "type": "object",
68 "properties": {
69 "id": {
70 "type": "string",
71 "description": "Stable id (device+inode); survives renames and moves"
72 },
73 "path": {
74 "type": "string",
75 "example": "/~/Photos/a.jpg"
76 },
77 "name": {
78 "type": "string"
79 },
80 "type": {
81 "type": "string",
82 "enum": [
83 "file",
84 "folder"
85 ]
86 },
87 "size": {
88 "type": "integer"
89 },
90 "mtime": {
91 "type": "string",
92 "format": "date-time"
93 },
94 "mtime_ms": {
95 "type": "integer"
96 },
97 "version": {
98 "type": "string",
99 "description": "Opaque version; also the ETag. Changes on every content change."
100 },
101 "sha256": {
102 "type": "string",
103 "nullable": true,
104 "description": "Hex SHA-256 when known (uploaded via API or requested with hash=1)"
105 }
106 }
107 },
108 "DeltaEntry": {
109 "type": "object",
110 "properties": {
111 "change": {
112 "type": "string",
113 "enum": [
114 "exists",
115 "created",
116 "modified",
117 "moved",
118 "deleted"
119 ]
120 },
121 "id": {
122 "type": "string"
123 },
124 "path": {
125 "type": "string"
126 },
127 "old_path": {
128 "type": "string",
129 "description": "Only for moved"
130 },
131 "type": {
132 "type": "string",
133 "enum": [
134 "file",
135 "folder"
136 ]
137 },
138 "size": {
139 "type": "integer",
140 "nullable": true
141 },
142 "mtime_ms": {
143 "type": "integer",
144 "nullable": true
145 },
146 "version": {
147 "type": "string",
148 "nullable": true
149 }
150 }
151 },
152 "Upload": {
153 "type": "object",
154 "properties": {
155 "id": {
156 "type": "string"
157 },
158 "path": {
159 "type": "string"
160 },
161 "size": {
162 "type": "integer"
163 },
164 "offset": {
165 "type": "integer"
166 },
167 "expires_at": {
168 "type": "string",
169 "format": "date-time"
170 },
171 "max_chunk_bytes": {
172 "type": "integer"
173 }
174 }
175 },
176 "Root": {
177 "type": "object",
178 "properties": {
179 "id": {
180 "type": "string",
181 "description": "'~' is the user's own folder"
182 },
183 "name": {
184 "type": "string"
185 },
186 "path": {
187 "type": "string"
188 },
189 "writable": {
190 "type": "boolean"
191 }
192 }
193 }
194 },
195 "responses": {
196 "Error": {
197 "description": "JSON error",
198 "content": {
199 "application/json": {
200 "schema": {
201 "$ref": "#/components/schemas/Error"
202 }
203 }
204 }
205 }
206 }
207 },
208 "paths": {
209 "/me": {
210 "get": {
211 "summary": "Current user, scopes, roots and limits",
212 "security": [
213 {
214 "oauth2": []
215 },
216 {
217 "personalToken": []
218 }
219 ],
220 "responses": {
221 "200": {
222 "description": "OK"
223 },
224 "401": {
225 "$ref": "#/components/responses/Error"
226 }
227 }
228 }
229 },
230 "/roots": {
231 "get": {
232 "summary": "Roots the user can read",
233 "security": [
234 {
235 "oauth2": [
236 "files:read"
237 ]
238 },
239 {
240 "personalToken": []
241 }
242 ],
243 "responses": {
244 "200": {
245 "description": "OK",
246 "content": {
247 "application/json": {
248 "schema": {
249 "type": "object",
250 "properties": {
251 "roots": {
252 "type": "array",
253 "items": {
254 "$ref": "#/components/schemas/Root"
255 }
256 }
257 }
258 }
259 }
260 }
261 },
262 "401": {
263 "$ref": "#/components/responses/Error"
264 }
265 }
266 }
267 },
268 "/files/metadata": {
269 "get": {
270 "summary": "Metadata of one file or folder",
271 "security": [
272 {
273 "oauth2": [
274 "files:read"
275 ]
276 },
277 {
278 "personalToken": []
279 }
280 ],
281 "parameters": [
282 {
283 "name": "path",
284 "in": "query",
285 "required": true,
286 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
287 "schema": {
288 "type": "string"
289 }
290 },
291 {
292 "name": "hash",
293 "in": "query",
294 "required": false,
295 "description": "1 = compute sha256 now if unknown (limited by api.maxHashBytes)",
296 "schema": {
297 "type": "string"
298 }
299 }
300 ],
301 "responses": {
302 "200": {
303 "description": "OK",
304 "content": {
305 "application/json": {
306 "schema": {
307 "$ref": "#/components/schemas/Entry"
308 }
309 }
310 }
311 },
312 "404": {
313 "$ref": "#/components/responses/Error"
314 }
315 }
316 }
317 },
318 "/files/list": {
319 "get": {
320 "summary": "List a folder (sorted by name, paged)",
321 "security": [
322 {
323 "oauth2": [
324 "files:read"
325 ]
326 },
327 {
328 "personalToken": []
329 }
330 ],
331 "parameters": [
332 {
333 "name": "path",
334 "in": "query",
335 "required": true,
336 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
337 "schema": {
338 "type": "string"
339 }
340 },
341 {
342 "name": "limit",
343 "in": "query",
344 "required": false,
345 "description": "1-1000, default 500",
346 "schema": {
347 "type": "integer"
348 }
349 },
350 {
351 "name": "page_token",
352 "in": "query",
353 "required": false,
354 "description": "From next_page_token",
355 "schema": {
356 "type": "string"
357 }
358 }
359 ],
360 "responses": {
361 "200": {
362 "description": "OK",
363 "content": {
364 "application/json": {
365 "schema": {
366 "type": "object",
367 "properties": {
368 "folder": {
369 "$ref": "#/components/schemas/Entry"
370 },
371 "entries": {
372 "type": "array",
373 "items": {
374 "$ref": "#/components/schemas/Entry"
375 }
376 },
377 "next_page_token": {
378 "type": "string",
379 "nullable": true
380 }
381 }
382 }
383 }
384 }
385 },
386 "404": {
387 "$ref": "#/components/responses/Error"
388 }
389 }
390 }
391 },
392 "/files/content": {
393 "get": {
394 "summary": "Download (supports Range, If-Range, If-None-Match)",
395 "security": [
396 {
397 "oauth2": [
398 "files:read"
399 ]
400 },
401 {
402 "personalToken": []
403 }
404 ],
405 "parameters": [
406 {
407 "name": "path",
408 "in": "query",
409 "required": true,
410 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
411 "schema": {
412 "type": "string"
413 }
414 },
415 {
416 "name": "Range",
417 "in": "header",
418 "required": false,
419 "description": "bytes=start-end",
420 "schema": {
421 "type": "string"
422 }
423 },
424 {
425 "name": "If-None-Match",
426 "in": "header",
427 "required": false,
428 "description": "Version/ETag",
429 "schema": {
430 "type": "string"
431 }
432 }
433 ],
434 "responses": {
435 "200": {
436 "description": "File bytes"
437 },
438 "206": {
439 "description": "Partial content"
440 },
441 "304": {
442 "description": "Not modified"
443 },
444 "404": {
445 "$ref": "#/components/responses/Error"
446 }
447 }
448 },
449 "put": {
450 "summary": "Upload a whole file in one request (small/medium files)",
451 "security": [
452 {
453 "oauth2": [
454 "files:write"
455 ]
456 },
457 {
458 "personalToken": []
459 }
460 ],
461 "parameters": [
462 {
463 "name": "path",
464 "in": "query",
465 "required": true,
466 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
467 "schema": {
468 "type": "string"
469 }
470 },
471 {
472 "name": "mtime",
473 "in": "query",
474 "required": false,
475 "description": "Epoch ms or ISO date to set as modification time",
476 "schema": {
477 "type": "string"
478 }
479 },
480 {
481 "name": "overwrite",
482 "in": "query",
483 "required": false,
484 "description": "true = replace without If-Match",
485 "schema": {
486 "type": "string"
487 }
488 },
489 {
490 "name": "If-Match",
491 "in": "header",
492 "required": false,
493 "description": "Replace only if current version matches",
494 "schema": {
495 "type": "string"
496 }
497 },
498 {
499 "name": "If-None-Match",
500 "in": "header",
501 "required": false,
502 "description": "* = create only",
503 "schema": {
504 "type": "string"
505 }
506 },
507 {
508 "name": "X-Content-SHA256",
509 "in": "header",
510 "required": false,
511 "description": "Hex SHA-256; verified before the file becomes visible",
512 "schema": {
513 "type": "string"
514 }
515 }
516 ],
517 "requestBody": {
518 "content": {
519 "application/octet-stream": {
520 "schema": {
521 "type": "string",
522 "format": "binary"
523 }
524 }
525 }
526 },
527 "responses": {
528 "200": {
529 "description": "Replaced",
530 "content": {
531 "application/json": {
532 "schema": {
533 "$ref": "#/components/schemas/Entry"
534 }
535 }
536 }
537 },
538 "201": {
539 "description": "Created",
540 "content": {
541 "application/json": {
542 "schema": {
543 "$ref": "#/components/schemas/Entry"
544 }
545 }
546 }
547 },
548 "403": {
549 "$ref": "#/components/responses/Error"
550 },
551 "409": {
552 "$ref": "#/components/responses/Error"
553 },
554 "412": {
555 "$ref": "#/components/responses/Error"
556 },
557 "413": {
558 "$ref": "#/components/responses/Error"
559 },
560 "422": {
561 "$ref": "#/components/responses/Error"
562 },
563 "507": {
564 "$ref": "#/components/responses/Error"
565 }
566 }
567 }
568 },
569 "/folders": {
570 "post": {
571 "summary": "Create a folder",
572 "security": [
573 {
574 "oauth2": [
575 "files:write"
576 ]
577 },
578 {
579 "personalToken": []
580 }
581 ],
582 "requestBody": {
583 "content": {
584 "application/json": {
585 "schema": {
586 "type": "object",
587 "required": [
588 "path"
589 ],
590 "properties": {
591 "path": {
592 "type": "string"
593 },
594 "parents": {
595 "type": "boolean"
596 },
597 "exist_ok": {
598 "type": "boolean"
599 }
600 }
601 }
602 }
603 }
604 },
605 "responses": {
606 "201": {
607 "description": "Created",
608 "content": {
609 "application/json": {
610 "schema": {
611 "$ref": "#/components/schemas/Entry"
612 }
613 }
614 }
615 },
616 "200": {
617 "description": "Already existed (exist_ok)",
618 "content": {
619 "application/json": {
620 "schema": {
621 "$ref": "#/components/schemas/Entry"
622 }
623 }
624 }
625 },
626 "409": {
627 "$ref": "#/components/responses/Error"
628 }
629 }
630 }
631 },
632 "/files/move": {
633 "post": {
634 "summary": "Rename or move (also between roots)",
635 "security": [
636 {
637 "oauth2": [
638 "files:write"
639 ]
640 },
641 {
642 "personalToken": []
643 }
644 ],
645 "requestBody": {
646 "content": {
647 "application/json": {
648 "schema": {
649 "type": "object",
650 "required": [
651 "from",
652 "to"
653 ],
654 "properties": {
655 "from": {
656 "type": "string"
657 },
658 "to": {
659 "type": "string"
660 },
661 "if_match": {
662 "type": "string"
663 },
664 "overwrite": {
665 "type": "boolean",
666 "description": "Replace an existing file at 'to' (never folders)"
667 }
668 }
669 }
670 }
671 }
672 },
673 "responses": {
674 "200": {
675 "description": "Moved",
676 "content": {
677 "application/json": {
678 "schema": {
679 "$ref": "#/components/schemas/Entry"
680 }
681 }
682 }
683 },
684 "409": {
685 "$ref": "#/components/responses/Error"
686 },
687 "412": {
688 "$ref": "#/components/responses/Error"
689 }
690 }
691 }
692 },
693 "/files": {
694 "delete": {
695 "summary": "Delete permanently (there is no trash)",
696 "security": [
697 {
698 "oauth2": [
699 "files:write"
700 ]
701 },
702 {
703 "personalToken": []
704 }
705 ],
706 "parameters": [
707 {
708 "name": "path",
709 "in": "query",
710 "required": true,
711 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
712 "schema": {
713 "type": "string"
714 }
715 },
716 {
717 "name": "recursive",
718 "in": "query",
719 "required": false,
720 "description": "true to delete a non-empty folder",
721 "schema": {
722 "type": "string"
723 }
724 },
725 {
726 "name": "If-Match",
727 "in": "header",
728 "required": false,
729 "description": "Only delete this version",
730 "schema": {
731 "type": "string"
732 }
733 }
734 ],
735 "responses": {
736 "204": {
737 "description": "Deleted"
738 },
739 "409": {
740 "$ref": "#/components/responses/Error"
741 },
742 "412": {
743 "$ref": "#/components/responses/Error"
744 }
745 }
746 }
747 },
748 "/delta": {
749 "get": {
750 "summary": "Change feed per root",
751 "description": "Without cursor: full snapshot (change=exists, reset=true), paged. Then pass the returned cursor to get created/modified/moved/deleted changes. Children of moved or deleted folders are implied. 410 means start over without a cursor.",
752 "security": [
753 {
754 "oauth2": [
755 "files:read"
756 ]
757 },
758 {
759 "personalToken": []
760 }
761 ],
762 "parameters": [
763 {
764 "name": "root",
765 "in": "query",
766 "required": false,
767 "description": "Root id (from /roots)",
768 "schema": {
769 "type": "string"
770 }
771 },
772 {
773 "name": "cursor",
774 "in": "query",
775 "required": false,
776 "description": "From the previous response",
777 "schema": {
778 "type": "string"
779 }
780 },
781 {
782 "name": "limit",
783 "in": "query",
784 "required": false,
785 "description": "1-1000, default 500",
786 "schema": {
787 "type": "integer"
788 }
789 }
790 ],
791 "responses": {
792 "200": {
793 "description": "OK",
794 "content": {
795 "application/json": {
796 "schema": {
797 "type": "object",
798 "properties": {
799 "reset": {
800 "type": "boolean"
801 },
802 "entries": {
803 "type": "array",
804 "items": {
805 "$ref": "#/components/schemas/DeltaEntry"
806 }
807 },
808 "cursor": {
809 "type": "string"
810 },
811 "has_more": {
812 "type": "boolean"
813 }
814 }
815 }
816 }
817 }
818 },
819 "400": {
820 "$ref": "#/components/responses/Error"
821 },
822 "410": {
823 "$ref": "#/components/responses/Error"
824 }
825 }
826 }
827 },
828 "/uploads": {
829 "post": {
830 "summary": "Start a resumable upload",
831 "security": [
832 {
833 "oauth2": [
834 "files:write"
835 ]
836 },
837 {
838 "personalToken": []
839 }
840 ],
841 "requestBody": {
842 "content": {
843 "application/json": {
844 "schema": {
845 "type": "object",
846 "required": [
847 "path",
848 "size"
849 ],
850 "properties": {
851 "path": {
852 "type": "string"
853 },
854 "size": {
855 "type": "integer"
856 },
857 "sha256": {
858 "type": "string"
859 },
860 "mtime": {
861 "type": "integer"
862 },
863 "if_match": {
864 "type": "string"
865 },
866 "if_none_match": {
867 "type": "string",
868 "enum": [
869 "*"
870 ]
871 },
872 "overwrite": {
873 "type": "boolean"
874 }
875 }
876 }
877 }
878 }
879 },
880 "responses": {
881 "201": {
882 "description": "Created",
883 "content": {
884 "application/json": {
885 "schema": {
886 "$ref": "#/components/schemas/Upload"
887 }
888 }
889 }
890 },
891 "409": {
892 "$ref": "#/components/responses/Error"
893 },
894 "412": {
895 "$ref": "#/components/responses/Error"
896 },
897 "413": {
898 "$ref": "#/components/responses/Error"
899 },
900 "429": {
901 "$ref": "#/components/responses/Error"
902 },
903 "507": {
904 "$ref": "#/components/responses/Error"
905 }
906 }
907 }
908 },
909 "/uploads/{id}": {
910 "parameters": [
911 {
912 "name": "id",
913 "in": "path",
914 "required": true,
915 "description": "Upload id",
916 "schema": {
917 "type": "string"
918 }
919 }
920 ],
921 "get": {
922 "summary": "Upload status (offset to resume from)",
923 "security": [
924 {
925 "oauth2": [
926 "files:write"
927 ]
928 },
929 {
930 "personalToken": []
931 }
932 ],
933 "responses": {
934 "200": {
935 "description": "OK",
936 "content": {
937 "application/json": {
938 "schema": {
939 "$ref": "#/components/schemas/Upload"
940 }
941 }
942 }
943 },
944 "404": {
945 "$ref": "#/components/responses/Error"
946 }
947 }
948 },
949 "patch": {
950 "summary": "Append a chunk at Upload-Offset",
951 "security": [
952 {
953 "oauth2": [
954 "files:write"
955 ]
956 },
957 {
958 "personalToken": []
959 }
960 ],
961 "parameters": [
962 {
963 "name": "Upload-Offset",
964 "in": "header",
965 "required": true,
966 "description": "Must equal the current offset",
967 "schema": {
968 "type": "integer"
969 }
970 }
971 ],
972 "requestBody": {
973 "content": {
974 "application/octet-stream": {
975 "schema": {
976 "type": "string",
977 "format": "binary"
978 }
979 }
980 }
981 },
982 "responses": {
983 "200": {
984 "description": "OK",
985 "content": {
986 "application/json": {
987 "schema": {
988 "$ref": "#/components/schemas/Upload"
989 }
990 }
991 }
992 },
993 "409": {
994 "$ref": "#/components/responses/Error"
995 },
996 "413": {
997 "$ref": "#/components/responses/Error"
998 }
999 }
1000 },
1001 "delete": {
1002 "summary": "Cancel",
1003 "security": [
1004 {
1005 "oauth2": [
1006 "files:write"
1007 ]
1008 },
1009 {
1010 "personalToken": []
1011 }
1012 ],
1013 "responses": {
1014 "204": {
1015 "description": "Cancelled"
1016 }
1017 }
1018 }
1019 },
1020 "/uploads/{id}/complete": {
1021 "parameters": [
1022 {
1023 "name": "id",
1024 "in": "path",
1025 "required": true,
1026 "description": "Upload id",
1027 "schema": {
1028 "type": "string"
1029 }
1030 }
1031 ],
1032 "post": {
1033 "summary": "Verify size/sha256 and atomically place the file",
1034 "security": [
1035 {
1036 "oauth2": [
1037 "files:write"
1038 ]
1039 },
1040 {
1041 "personalToken": []
1042 }
1043 ],
1044 "responses": {
1045 "200": {
1046 "description": "Replaced",
1047 "content": {
1048 "application/json": {
1049 "schema": {
1050 "$ref": "#/components/schemas/Entry"
1051 }
1052 }
1053 }
1054 },
1055 "201": {
1056 "description": "Created",
1057 "content": {
1058 "application/json": {
1059 "schema": {
1060 "$ref": "#/components/schemas/Entry"
1061 }
1062 }
1063 }
1064 },
1065 "409": {
1066 "$ref": "#/components/responses/Error"
1067 },
1068 "412": {
1069 "$ref": "#/components/responses/Error"
1070 },
1071 "422": {
1072 "$ref": "#/components/responses/Error"
1073 }
1074 }
1075 }
1076 }
1077 }
1078 }
@@ -0,0 +1,1078 @@
1{
2 "openapi": "3.0.3",
3 "info": {
4 "title": "Filemanager sync API",
5 "version": "1.0.0",
6 "description": "Versioned API for sync clients (phone, desktop, services). See docs/api.md for the OAuth flow and a sync walkthrough. A token can never see or change more than its user can in the web UI."
7 },
8 "servers": [
9 {
10 "url": "/api/v1"
11 }
12 ],
13 "components": {
14 "securitySchemes": {
15 "oauth2": {
16 "type": "oauth2",
17 "description": "Authorization code with PKCE (S256), public clients without secret.",
18 "flows": {
19 "authorizationCode": {
20 "authorizationUrl": "/oauth/authorize",
21 "tokenUrl": "/oauth/token",
22 "refreshUrl": "/oauth/token",
23 "scopes": {
24 "files:read": "Read and download files",
25 "files:write": "Upload, create, move and delete (implies files:read)"
26 }
27 }
28 }
29 },
30 "personalToken": {
31 "type": "http",
32 "scheme": "bearer",
33 "description": "Personal access token (fmp_...) created on /apps.html"
34 }
35 },
36 "schemas": {
37 "Error": {
38 "type": "object",
39 "required": [
40 "error",
41 "message"
42 ],
43 "properties": {
44 "error": {
45 "type": "string",
46 "example": "conflict"
47 },
48 "message": {
49 "type": "string"
50 },
51 "current": {
52 "allOf": [
53 {
54 "$ref": "#/components/schemas/Entry"
55 }
56 ],
57 "nullable": true,
58 "description": "Current state of the target on 409/412"
59 },
60 "offset": {
61 "type": "integer",
62 "description": "Server offset on upload offset errors"
63 }
64 }
65 },
66 "Entry": {
67 "type": "object",
68 "properties": {
69 "id": {
70 "type": "string",
71 "description": "Stable id (device+inode); survives renames and moves"
72 },
73 "path": {
74 "type": "string",
75 "example": "/~/Photos/a.jpg"
76 },
77 "name": {
78 "type": "string"
79 },
80 "type": {
81 "type": "string",
82 "enum": [
83 "file",
84 "folder"
85 ]
86 },
87 "size": {
88 "type": "integer"
89 },
90 "mtime": {
91 "type": "string",
92 "format": "date-time"
93 },
94 "mtime_ms": {
95 "type": "integer"
96 },
97 "version": {
98 "type": "string",
99 "description": "Opaque version; also the ETag. Changes on every content change."
100 },
101 "sha256": {
102 "type": "string",
103 "nullable": true,
104 "description": "Hex SHA-256 when known (uploaded via API or requested with hash=1)"
105 }
106 }
107 },
108 "DeltaEntry": {
109 "type": "object",
110 "properties": {
111 "change": {
112 "type": "string",
113 "enum": [
114 "exists",
115 "created",
116 "modified",
117 "moved",
118 "deleted"
119 ]
120 },
121 "id": {
122 "type": "string"
123 },
124 "path": {
125 "type": "string"
126 },
127 "old_path": {
128 "type": "string",
129 "description": "Only for moved"
130 },
131 "type": {
132 "type": "string",
133 "enum": [
134 "file",
135 "folder"
136 ]
137 },
138 "size": {
139 "type": "integer",
140 "nullable": true
141 },
142 "mtime_ms": {
143 "type": "integer",
144 "nullable": true
145 },
146 "version": {
147 "type": "string",
148 "nullable": true
149 }
150 }
151 },
152 "Upload": {
153 "type": "object",
154 "properties": {
155 "id": {
156 "type": "string"
157 },
158 "path": {
159 "type": "string"
160 },
161 "size": {
162 "type": "integer"
163 },
164 "offset": {
165 "type": "integer"
166 },
167 "expires_at": {
168 "type": "string",
169 "format": "date-time"
170 },
171 "max_chunk_bytes": {
172 "type": "integer"
173 }
174 }
175 },
176 "Root": {
177 "type": "object",
178 "properties": {
179 "id": {
180 "type": "string",
181 "description": "'~' is the user's own folder"
182 },
183 "name": {
184 "type": "string"
185 },
186 "path": {
187 "type": "string"
188 },
189 "writable": {
190 "type": "boolean"
191 }
192 }
193 }
194 },
195 "responses": {
196 "Error": {
197 "description": "JSON error",
198 "content": {
199 "application/json": {
200 "schema": {
201 "$ref": "#/components/schemas/Error"
202 }
203 }
204 }
205 }
206 }
207 },
208 "paths": {
209 "/me": {
210 "get": {
211 "summary": "Current user, scopes, roots and limits",
212 "security": [
213 {
214 "oauth2": []
215 },
216 {
217 "personalToken": []
218 }
219 ],
220 "responses": {
221 "200": {
222 "description": "OK"
223 },
224 "401": {
225 "$ref": "#/components/responses/Error"
226 }
227 }
228 }
229 },
230 "/roots": {
231 "get": {
232 "summary": "Roots the user can read",
233 "security": [
234 {
235 "oauth2": [
236 "files:read"
237 ]
238 },
239 {
240 "personalToken": []
241 }
242 ],
243 "responses": {
244 "200": {
245 "description": "OK",
246 "content": {
247 "application/json": {
248 "schema": {
249 "type": "object",
250 "properties": {
251 "roots": {
252 "type": "array",
253 "items": {
254 "$ref": "#/components/schemas/Root"
255 }
256 }
257 }
258 }
259 }
260 }
261 },
262 "401": {
263 "$ref": "#/components/responses/Error"
264 }
265 }
266 }
267 },
268 "/files/metadata": {
269 "get": {
270 "summary": "Metadata of one file or folder",
271 "security": [
272 {
273 "oauth2": [
274 "files:read"
275 ]
276 },
277 {
278 "personalToken": []
279 }
280 ],
281 "parameters": [
282 {
283 "name": "path",
284 "in": "query",
285 "required": true,
286 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
287 "schema": {
288 "type": "string"
289 }
290 },
291 {
292 "name": "hash",
293 "in": "query",
294 "required": false,
295 "description": "1 = compute sha256 now if unknown (limited by api.maxHashBytes)",
296 "schema": {
297 "type": "string"
298 }
299 }
300 ],
301 "responses": {
302 "200": {
303 "description": "OK",
304 "content": {
305 "application/json": {
306 "schema": {
307 "$ref": "#/components/schemas/Entry"
308 }
309 }
310 }
311 },
312 "404": {
313 "$ref": "#/components/responses/Error"
314 }
315 }
316 }
317 },
318 "/files/list": {
319 "get": {
320 "summary": "List a folder (sorted by name, paged)",
321 "security": [
322 {
323 "oauth2": [
324 "files:read"
325 ]
326 },
327 {
328 "personalToken": []
329 }
330 ],
331 "parameters": [
332 {
333 "name": "path",
334 "in": "query",
335 "required": true,
336 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
337 "schema": {
338 "type": "string"
339 }
340 },
341 {
342 "name": "limit",
343 "in": "query",
344 "required": false,
345 "description": "1-1000, default 500",
346 "schema": {
347 "type": "integer"
348 }
349 },
350 {
351 "name": "page_token",
352 "in": "query",
353 "required": false,
354 "description": "From next_page_token",
355 "schema": {
356 "type": "string"
357 }
358 }
359 ],
360 "responses": {
361 "200": {
362 "description": "OK",
363 "content": {
364 "application/json": {
365 "schema": {
366 "type": "object",
367 "properties": {
368 "folder": {
369 "$ref": "#/components/schemas/Entry"
370 },
371 "entries": {
372 "type": "array",
373 "items": {
374 "$ref": "#/components/schemas/Entry"
375 }
376 },
377 "next_page_token": {
378 "type": "string",
379 "nullable": true
380 }
381 }
382 }
383 }
384 }
385 },
386 "404": {
387 "$ref": "#/components/responses/Error"
388 }
389 }
390 }
391 },
392 "/files/content": {
393 "get": {
394 "summary": "Download (supports Range, If-Range, If-None-Match)",
395 "security": [
396 {
397 "oauth2": [
398 "files:read"
399 ]
400 },
401 {
402 "personalToken": []
403 }
404 ],
405 "parameters": [
406 {
407 "name": "path",
408 "in": "query",
409 "required": true,
410 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
411 "schema": {
412 "type": "string"
413 }
414 },
415 {
416 "name": "Range",
417 "in": "header",
418 "required": false,
419 "description": "bytes=start-end",
420 "schema": {
421 "type": "string"
422 }
423 },
424 {
425 "name": "If-None-Match",
426 "in": "header",
427 "required": false,
428 "description": "Version/ETag",
429 "schema": {
430 "type": "string"
431 }
432 }
433 ],
434 "responses": {
435 "200": {
436 "description": "File bytes"
437 },
438 "206": {
439 "description": "Partial content"
440 },
441 "304": {
442 "description": "Not modified"
443 },
444 "404": {
445 "$ref": "#/components/responses/Error"
446 }
447 }
448 },
449 "put": {
450 "summary": "Upload a whole file in one request (small/medium files)",
451 "security": [
452 {
453 "oauth2": [
454 "files:write"
455 ]
456 },
457 {
458 "personalToken": []
459 }
460 ],
461 "parameters": [
462 {
463 "name": "path",
464 "in": "query",
465 "required": true,
466 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
467 "schema": {
468 "type": "string"
469 }
470 },
471 {
472 "name": "mtime",
473 "in": "query",
474 "required": false,
475 "description": "Epoch ms or ISO date to set as modification time",
476 "schema": {
477 "type": "string"
478 }
479 },
480 {
481 "name": "overwrite",
482 "in": "query",
483 "required": false,
484 "description": "true = replace without If-Match",
485 "schema": {
486 "type": "string"
487 }
488 },
489 {
490 "name": "If-Match",
491 "in": "header",
492 "required": false,
493 "description": "Replace only if current version matches",
494 "schema": {
495 "type": "string"
496 }
497 },
498 {
499 "name": "If-None-Match",
500 "in": "header",
501 "required": false,
502 "description": "* = create only",
503 "schema": {
504 "type": "string"
505 }
506 },
507 {
508 "name": "X-Content-SHA256",
509 "in": "header",
510 "required": false,
511 "description": "Hex SHA-256; verified before the file becomes visible",
512 "schema": {
513 "type": "string"
514 }
515 }
516 ],
517 "requestBody": {
518 "content": {
519 "application/octet-stream": {
520 "schema": {
521 "type": "string",
522 "format": "binary"
523 }
524 }
525 }
526 },
527 "responses": {
528 "200": {
529 "description": "Replaced",
530 "content": {
531 "application/json": {
532 "schema": {
533 "$ref": "#/components/schemas/Entry"
534 }
535 }
536 }
537 },
538 "201": {
539 "description": "Created",
540 "content": {
541 "application/json": {
542 "schema": {
543 "$ref": "#/components/schemas/Entry"
544 }
545 }
546 }
547 },
548 "403": {
549 "$ref": "#/components/responses/Error"
550 },
551 "409": {
552 "$ref": "#/components/responses/Error"
553 },
554 "412": {
555 "$ref": "#/components/responses/Error"
556 },
557 "413": {
558 "$ref": "#/components/responses/Error"
559 },
560 "422": {
561 "$ref": "#/components/responses/Error"
562 },
563 "507": {
564 "$ref": "#/components/responses/Error"
565 }
566 }
567 }
568 },
569 "/folders": {
570 "post": {
571 "summary": "Create a folder",
572 "security": [
573 {
574 "oauth2": [
575 "files:write"
576 ]
577 },
578 {
579 "personalToken": []
580 }
581 ],
582 "requestBody": {
583 "content": {
584 "application/json": {
585 "schema": {
586 "type": "object",
587 "required": [
588 "path"
589 ],
590 "properties": {
591 "path": {
592 "type": "string"
593 },
594 "parents": {
595 "type": "boolean"
596 },
597 "exist_ok": {
598 "type": "boolean"
599 }
600 }
601 }
602 }
603 }
604 },
605 "responses": {
606 "201": {
607 "description": "Created",
608 "content": {
609 "application/json": {
610 "schema": {
611 "$ref": "#/components/schemas/Entry"
612 }
613 }
614 }
615 },
616 "200": {
617 "description": "Already existed (exist_ok)",
618 "content": {
619 "application/json": {
620 "schema": {
621 "$ref": "#/components/schemas/Entry"
622 }
623 }
624 }
625 },
626 "409": {
627 "$ref": "#/components/responses/Error"
628 }
629 }
630 }
631 },
632 "/files/move": {
633 "post": {
634 "summary": "Rename or move (also between roots)",
635 "security": [
636 {
637 "oauth2": [
638 "files:write"
639 ]
640 },
641 {
642 "personalToken": []
643 }
644 ],
645 "requestBody": {
646 "content": {
647 "application/json": {
648 "schema": {
649 "type": "object",
650 "required": [
651 "from",
652 "to"
653 ],
654 "properties": {
655 "from": {
656 "type": "string"
657 },
658 "to": {
659 "type": "string"
660 },
661 "if_match": {
662 "type": "string"
663 },
664 "overwrite": {
665 "type": "boolean",
666 "description": "Replace an existing file at 'to' (never folders)"
667 }
668 }
669 }
670 }
671 }
672 },
673 "responses": {
674 "200": {
675 "description": "Moved",
676 "content": {
677 "application/json": {
678 "schema": {
679 "$ref": "#/components/schemas/Entry"
680 }
681 }
682 }
683 },
684 "409": {
685 "$ref": "#/components/responses/Error"
686 },
687 "412": {
688 "$ref": "#/components/responses/Error"
689 }
690 }
691 }
692 },
693 "/files": {
694 "delete": {
695 "summary": "Delete permanently (there is no trash)",
696 "security": [
697 {
698 "oauth2": [
699 "files:write"
700 ]
701 },
702 {
703 "personalToken": []
704 }
705 ],
706 "parameters": [
707 {
708 "name": "path",
709 "in": "query",
710 "required": true,
711 "description": "Virtual path: /<root-id>/<relative path>, e.g. /~/Photos/a.jpg",
712 "schema": {
713 "type": "string"
714 }
715 },
716 {
717 "name": "recursive",
718 "in": "query",
719 "required": false,
720 "description": "true to delete a non-empty folder",
721 "schema": {
722 "type": "string"
723 }
724 },
725 {
726 "name": "If-Match",
727 "in": "header",
728 "required": false,
729 "description": "Only delete this version",
730 "schema": {
731 "type": "string"
732 }
733 }
734 ],
735 "responses": {
736 "204": {
737 "description": "Deleted"
738 },
739 "409": {
740 "$ref": "#/components/responses/Error"
741 },
742 "412": {
743 "$ref": "#/components/responses/Error"
744 }
745 }
746 }
747 },
748 "/delta": {
749 "get": {
750 "summary": "Change feed per root",
751 "description": "Without cursor: full snapshot (change=exists, reset=true), paged. Then pass the returned cursor to get created/modified/moved/deleted changes. Children of moved or deleted folders are implied. 410 means start over without a cursor.",
752 "security": [
753 {
754 "oauth2": [
755 "files:read"
756 ]
757 },
758 {
759 "personalToken": []
760 }
761 ],
762 "parameters": [
763 {
764 "name": "root",
765 "in": "query",
766 "required": false,
767 "description": "Root id (from /roots)",
768 "schema": {
769 "type": "string"
770 }
771 },
772 {
773 "name": "cursor",
774 "in": "query",
775 "required": false,
776 "description": "From the previous response",
777 "schema": {
778 "type": "string"
779 }
780 },
781 {
782 "name": "limit",
783 "in": "query",
784 "required": false,
785 "description": "1-1000, default 500",
786 "schema": {
787 "type": "integer"
788 }
789 }
790 ],
791 "responses": {
792 "200": {
793 "description": "OK",
794 "content": {
795 "application/json": {
796 "schema": {
797 "type": "object",
798 "properties": {
799 "reset": {
800 "type": "boolean"
801 },
802 "entries": {
803 "type": "array",
804 "items": {
805 "$ref": "#/components/schemas/DeltaEntry"
806 }
807 },
808 "cursor": {
809 "type": "string"
810 },
811 "has_more": {
812 "type": "boolean"
813 }
814 }
815 }
816 }
817 }
818 },
819 "400": {
820 "$ref": "#/components/responses/Error"
821 },
822 "410": {
823 "$ref": "#/components/responses/Error"
824 }
825 }
826 }
827 },
828 "/uploads": {
829 "post": {
830 "summary": "Start a resumable upload",
831 "security": [
832 {
833 "oauth2": [
834 "files:write"
835 ]
836 },
837 {
838 "personalToken": []
839 }
840 ],
841 "requestBody": {
842 "content": {
843 "application/json": {
844 "schema": {
845 "type": "object",
846 "required": [
847 "path",
848 "size"
849 ],
850 "properties": {
851 "path": {
852 "type": "string"
853 },
854 "size": {
855 "type": "integer"
856 },
857 "sha256": {
858 "type": "string"
859 },
860 "mtime": {
861 "type": "integer"
862 },
863 "if_match": {
864 "type": "string"
865 },
866 "if_none_match": {
867 "type": "string",
868 "enum": [
869 "*"
870 ]
871 },
872 "overwrite": {
873 "type": "boolean"
874 }
875 }
876 }
877 }
878 }
879 },
880 "responses": {
881 "201": {
882 "description": "Created",
883 "content": {
884 "application/json": {
885 "schema": {
886 "$ref": "#/components/schemas/Upload"
887 }
888 }
889 }
890 },
891 "409": {
892 "$ref": "#/components/responses/Error"
893 },
894 "412": {
895 "$ref": "#/components/responses/Error"
896 },
897 "413": {
898 "$ref": "#/components/responses/Error"
899 },
900 "429": {
901 "$ref": "#/components/responses/Error"
902 },
903 "507": {
904 "$ref": "#/components/responses/Error"
905 }
906 }
907 }
908 },
909 "/uploads/{id}": {
910 "parameters": [
911 {
912 "name": "id",
913 "in": "path",
914 "required": true,
915 "description": "Upload id",
916 "schema": {
917 "type": "string"
918 }
919 }
920 ],
921 "get": {
922 "summary": "Upload status (offset to resume from)",
923 "security": [
924 {
925 "oauth2": [
926 "files:write"
927 ]
928 },
929 {
930 "personalToken": []
931 }
932 ],
933 "responses": {
934 "200": {
935 "description": "OK",
936 "content": {
937 "application/json": {
938 "schema": {
939 "$ref": "#/components/schemas/Upload"
940 }
941 }
942 }
943 },
944 "404": {
945 "$ref": "#/components/responses/Error"
946 }
947 }
948 },
949 "patch": {
950 "summary": "Append a chunk at Upload-Offset",
951 "security": [
952 {
953 "oauth2": [
954 "files:write"
955 ]
956 },
957 {
958 "personalToken": []
959 }
960 ],
961 "parameters": [
962 {
963 "name": "Upload-Offset",
964 "in": "header",
965 "required": true,
966 "description": "Must equal the current offset",
967 "schema": {
968 "type": "integer"
969 }
970 }
971 ],
972 "requestBody": {
973 "content": {
974 "application/octet-stream": {
975 "schema": {
976 "type": "string",
977 "format": "binary"
978 }
979 }
980 }
981 },
982 "responses": {
983 "200": {
984 "description": "OK",
985 "content": {
986 "application/json": {
987 "schema": {
988 "$ref": "#/components/schemas/Upload"
989 }
990 }
991 }
992 },
993 "409": {
994 "$ref": "#/components/responses/Error"
995 },
996 "413": {
997 "$ref": "#/components/responses/Error"
998 }
999 }
1000 },
1001 "delete": {
1002 "summary": "Cancel",
1003 "security": [
1004 {
1005 "oauth2": [
1006 "files:write"
1007 ]
1008 },
1009 {
1010 "personalToken": []
1011 }
1012 ],
1013 "responses": {
1014 "204": {
1015 "description": "Cancelled"
1016 }
1017 }
1018 }
1019 },
1020 "/uploads/{id}/complete": {
1021 "parameters": [
1022 {
1023 "name": "id",
1024 "in": "path",
1025 "required": true,
1026 "description": "Upload id",
1027 "schema": {
1028 "type": "string"
1029 }
1030 }
1031 ],
1032 "post": {
1033 "summary": "Verify size/sha256 and atomically place the file",
1034 "security": [
1035 {
1036 "oauth2": [
1037 "files:write"
1038 ]
1039 },
1040 {
1041 "personalToken": []
1042 }
1043 ],
1044 "responses": {
1045 "200": {
1046 "description": "Replaced",
1047 "content": {
1048 "application/json": {
1049 "schema": {
1050 "$ref": "#/components/schemas/Entry"
1051 }
1052 }
1053 }
1054 },
1055 "201": {
1056 "description": "Created",
1057 "content": {
1058 "application/json": {
1059 "schema": {
1060 "$ref": "#/components/schemas/Entry"
1061 }
1062 }
1063 }
1064 },
1065 "409": {
1066 "$ref": "#/components/responses/Error"
1067 },
1068 "412": {
1069 "$ref": "#/components/responses/Error"
1070 },
1071 "422": {
1072 "$ref": "#/components/responses/Error"
1073 }
1074 }
1075 }
1076 }
1077 }
1078}
public/apps.html added +188 −0
@@ -0,0 +1,188 @@
1 <!doctype html>
2 <html lang="en">
3 <head>
4 <meta charset="utf-8">
5 <meta name="viewport" content="width=device-width,initial-scale=1">
6 <title>Connected apps &amp; API access</title>
7 <style>
8 body{font-family:system-ui,sans-serif;background:#f4f5f7;margin:0;padding:1rem;color:#222}
9 main{max-width:46rem;margin:0 auto}
10 section{background:#fff;border-radius:10px;padding:1rem 1.25rem;margin:1rem 0;box-shadow:0 1px 4px #0002}
11 table{width:100%;border-collapse:collapse}td,th{text-align:left;padding:.4rem;border-bottom:1px solid #eee;vertical-align:top;font-size:.92rem}
12 button{padding:.4rem .8rem;border-radius:6px;border:1px solid #888;background:#fff;cursor:pointer}
13 button.danger{border-color:#b42318;color:#b42318}
14 input,select{padding:.4rem;font-size:.95rem}
15 code{background:#f0f0f0;padding:.15rem .3rem;border-radius:4px;word-break:break-all}
16 .muted{color:#666;font-size:.85rem}.err{color:#b42318}
17 @media (max-width:600px){td,th{display:block;border:0}tr{display:block;border-bottom:1px solid #eee;padding:.4rem 0}}
18 </style>
19 </head>
20 <body>
21 <main>
22 <h1>Connected apps &amp; API access</h1>
23 <p class="muted">Apps and devices you allowed to use your files through the API. They can never see more than you can. <a href="/">Back to files</a></p>
24 <p id="msg" class="err"></p>
25
26 <section>
27 <h2>Authorised apps and tokens</h2>
28 <table><thead><tr><th>Name</th><th>Type</th><th>Access</th><th>Last used</th><th></th></tr></thead><tbody id="grants"></tbody></table>
29 <p><button class="danger" id="revokeAll">Revoke everything</button></p>
30 </section>
31
32 <section>
33 <h2>New personal access token</h2>
34 <p class="muted">For scripts and your own tools. Prefer OAuth for apps other people build.</p>
35 <form id="patForm">
36 <input id="patName" placeholder="Name, e.g. backup script" required maxlength="80">
37 <select id="patScope"><option value="files:read">Read only</option><option value="files:read files:write">Read and write</option></select>
38 <select id="patDays"><option value="30">30 days</option><option value="90">90 days</option><option value="365">1 year</option><option value="">No expiry</option></select>
39 <button type="submit">Create</button>
40 </form>
41 <p id="patOut"></p>
42 </section>
43
44 <section id="clientsSection" hidden>
45 <h2>OAuth clients (admin)</h2>
46 <p class="muted">Register an app before it can ask users for access. Redirect URIs: https://…, http://127.0.0.1/… (any port) or a private scheme like <code>com.example.sync:/callback</code>.</p>
47 <table><thead><tr><th>Name</th><th>client_id</th><th>Redirect URIs</th><th></th></tr></thead><tbody id="clients"></tbody></table>
48 <form id="clientForm">
49 <input id="clientName" placeholder="App name" required maxlength="80">
50 <input id="clientUris" placeholder="Redirect URIs, comma separated" required size="40">
51 <button type="submit">Register</button>
52 </form>
53 </section>
54 </main>
55 <script>
56 (function ()
57 {
58 'use strict';
59 const SESSION_KEY = 'filemanager.session.v1';
60 const CLIENT_BINDING_KEY = 'filemanager.client-binding-id.v1';
61 const BASE = '/api/account/api-access';
62
63 function fingerprint ()
64 {
65 const nav = navigator;
66 return [
67 localStorage.getItem(CLIENT_BINDING_KEY) || '',
68 nav.userAgent || '',
69 nav.language,
70 nav.platform || (nav.userAgentData && nav.userAgentData.platform) || '',
71 Intl.DateTimeFormat().resolvedOptions().timeZone,
72 ].join('|');
73 }
74
75 function token ()
76 {
77 try { return JSON.parse(localStorage.getItem(SESSION_KEY) || 'null').token; } catch { return null; }
78 }
79
80 const msg = document.getElementById('msg');
81
82 async function call (method, url, body)
83 {
84 const res = await fetch(url, {
85 method,
86 headers: { Authorization: 'Bearer ' + token(), 'X-Fp': fingerprint(), 'Content-Type': 'application/json' },
87 body: body ? JSON.stringify(body) : undefined,
88 });
89 const data = await res.json().catch(() => ({}));
90 if (res.status === 401) { msg.textContent = 'Please log in to the file manager first, then reload this page.'; throw new Error('auth'); }
91 if (!res.ok) { msg.textContent = data.error || 'Request failed.'; throw new Error(data.error); }
92 msg.textContent = '';
93 return data;
94 }
95
96 function cell (tr, text)
97 {
98 const td = document.createElement('td');
99 if (text instanceof Node) td.appendChild(text); else td.textContent = text;
100 tr.appendChild(td);
101 return td;
102 }
103
104 function when (ms) { return ms ? new Date(ms).toLocaleString() : 'never'; }
105
106 async function loadGrants ()
107 {
108 const data = await call('GET', BASE + '/grants');
109 const tb = document.getElementById('grants');
110 tb.textContent = '';
111 if (!data.grants.length)
112 {
113 const tr = document.createElement('tr'); cell(tr, 'Nothing authorised yet.'); tb.appendChild(tr);
114 }
115 for (const g of data.grants)
116 {
117 const tr = document.createElement('tr');
118 cell(tr, g.name + (g.clientName && g.clientName !== g.name ? ' (' + g.clientName + ')' : ''));
119 cell(tr, g.kind === 'oauth' ? 'App / device' : 'Personal token');
120 cell(tr, g.scopes.includes('files:write') ? 'Read and write' : 'Read only');
121 cell(tr, when(g.lastUsedAt) + (g.lastUsedIp ? ' from ' + g.lastUsedIp : ''));
122 const btn = document.createElement('button');
123 btn.className = 'danger'; btn.textContent = 'Revoke';
124 btn.onclick = async () => { if (confirm('Revoke access for ' + g.name + '?')) { await call('DELETE', BASE + '/grants/' + encodeURIComponent(g.id)); loadGrants(); } };
125 cell(tr, btn);
126 tb.appendChild(tr);
127 }
128 }
129
130 async function loadClients ()
131 {
132 let data;
133 try { data = await call('GET', BASE + '/clients'); } catch { msg.textContent = ''; return; }
134 document.getElementById('clientsSection').hidden = false;
135 const tb = document.getElementById('clients');
136 tb.textContent = '';
137 for (const c of data.clients)
138 {
139 const tr = document.createElement('tr');
140 cell(tr, c.name);
141 const code = document.createElement('code'); code.textContent = c.clientId; cell(tr, code);
142 cell(tr, c.redirectUris.join(', '));
143 const btn = document.createElement('button');
144 btn.className = 'danger'; btn.textContent = 'Delete';
145 btn.onclick = async () => { if (confirm('Delete ' + c.name + '? All its grants are revoked.')) { await call('DELETE', BASE + '/clients/' + encodeURIComponent(c.clientId)); loadClients(); loadGrants(); } };
146 cell(tr, btn);
147 tb.appendChild(tr);
148 }
149 }
150
151 document.getElementById('revokeAll').onclick = async () =>
152 {
153 if (!confirm('Revoke access for every app, device and token?')) return;
154 await call('POST', BASE + '/grants/revoke-all');
155 loadGrants();
156 };
157
158 document.getElementById('patForm').onsubmit = async (e) =>
159 {
160 e.preventDefault();
161 const out = document.getElementById('patOut');
162 const data = await call('POST', BASE + '/tokens', {
163 name: document.getElementById('patName').value,
164 scopes: document.getElementById('patScope').value,
165 expiresInDays: document.getElementById('patDays').value || null,
166 });
167 out.textContent = 'Copy this token now, it is shown only once: ';
168 const code = document.createElement('code'); code.textContent = data.token; out.appendChild(code);
169 loadGrants();
170 };
171
172 document.getElementById('clientForm').onsubmit = async (e) =>
173 {
174 e.preventDefault();
175 await call('POST', BASE + '/clients', {
176 name: document.getElementById('clientName').value,
177 redirectUris: document.getElementById('clientUris').value.split(',').map((s) => s.trim()).filter(Boolean),
178 });
179 e.target.reset();
180 loadClients();
181 };
182
183 if (!token()) { msg.textContent = 'Please log in to the file manager first, then reload this page.'; return; }
184 loadGrants().then(loadClients).catch(() => {});
185 })();
186 </script>
187 </body>
188 </html>
@@ -0,0 +1,188 @@
1<!doctype html>
2<html lang="en">
3<head>
4<meta charset="utf-8">
5<meta name="viewport" content="width=device-width,initial-scale=1">
6<title>Connected apps &amp; API access</title>
7<style>
8body{font-family:system-ui,sans-serif;background:#f4f5f7;margin:0;padding:1rem;color:#222}
9main{max-width:46rem;margin:0 auto}
10section{background:#fff;border-radius:10px;padding:1rem 1.25rem;margin:1rem 0;box-shadow:0 1px 4px #0002}
11table{width:100%;border-collapse:collapse}td,th{text-align:left;padding:.4rem;border-bottom:1px solid #eee;vertical-align:top;font-size:.92rem}
12button{padding:.4rem .8rem;border-radius:6px;border:1px solid #888;background:#fff;cursor:pointer}
13button.danger{border-color:#b42318;color:#b42318}
14input,select{padding:.4rem;font-size:.95rem}
15code{background:#f0f0f0;padding:.15rem .3rem;border-radius:4px;word-break:break-all}
16.muted{color:#666;font-size:.85rem}.err{color:#b42318}
17@media (max-width:600px){td,th{display:block;border:0}tr{display:block;border-bottom:1px solid #eee;padding:.4rem 0}}
18</style>
19</head>
20<body>
21<main>
22<h1>Connected apps &amp; API access</h1>
23<p class="muted">Apps and devices you allowed to use your files through the API. They can never see more than you can. <a href="/">Back to files</a></p>
24<p id="msg" class="err"></p>
25
26<section>
27<h2>Authorised apps and tokens</h2>
28<table><thead><tr><th>Name</th><th>Type</th><th>Access</th><th>Last used</th><th></th></tr></thead><tbody id="grants"></tbody></table>
29<p><button class="danger" id="revokeAll">Revoke everything</button></p>
30</section>
31
32<section>
33<h2>New personal access token</h2>
34<p class="muted">For scripts and your own tools. Prefer OAuth for apps other people build.</p>
35<form id="patForm">
36<input id="patName" placeholder="Name, e.g. backup script" required maxlength="80">
37<select id="patScope"><option value="files:read">Read only</option><option value="files:read files:write">Read and write</option></select>
38<select id="patDays"><option value="30">30 days</option><option value="90">90 days</option><option value="365">1 year</option><option value="">No expiry</option></select>
39<button type="submit">Create</button>
40</form>
41<p id="patOut"></p>
42</section>
43
44<section id="clientsSection" hidden>
45<h2>OAuth clients (admin)</h2>
46<p class="muted">Register an app before it can ask users for access. Redirect URIs: https://…, http://127.0.0.1/… (any port) or a private scheme like <code>com.example.sync:/callback</code>.</p>
47<table><thead><tr><th>Name</th><th>client_id</th><th>Redirect URIs</th><th></th></tr></thead><tbody id="clients"></tbody></table>
48<form id="clientForm">
49<input id="clientName" placeholder="App name" required maxlength="80">
50<input id="clientUris" placeholder="Redirect URIs, comma separated" required size="40">
51<button type="submit">Register</button>
52</form>
53</section>
54</main>
55<script>
56(function ()
57{
58 'use strict';
59 const SESSION_KEY = 'filemanager.session.v1';
60 const CLIENT_BINDING_KEY = 'filemanager.client-binding-id.v1';
61 const BASE = '/api/account/api-access';
62
63 function fingerprint ()
64 {
65 const nav = navigator;
66 return [
67 localStorage.getItem(CLIENT_BINDING_KEY) || '',
68 nav.userAgent || '',
69 nav.language,
70 nav.platform || (nav.userAgentData && nav.userAgentData.platform) || '',
71 Intl.DateTimeFormat().resolvedOptions().timeZone,
72 ].join('|');
73 }
74
75 function token ()
76 {
77 try { return JSON.parse(localStorage.getItem(SESSION_KEY) || 'null').token; } catch { return null; }
78 }
79
80 const msg = document.getElementById('msg');
81
82 async function call (method, url, body)
83 {
84 const res = await fetch(url, {
85 method,
86 headers: { Authorization: 'Bearer ' + token(), 'X-Fp': fingerprint(), 'Content-Type': 'application/json' },
87 body: body ? JSON.stringify(body) : undefined,
88 });
89 const data = await res.json().catch(() => ({}));
90 if (res.status === 401) { msg.textContent = 'Please log in to the file manager first, then reload this page.'; throw new Error('auth'); }
91 if (!res.ok) { msg.textContent = data.error || 'Request failed.'; throw new Error(data.error); }
92 msg.textContent = '';
93 return data;
94 }
95
96 function cell (tr, text)
97 {
98 const td = document.createElement('td');
99 if (text instanceof Node) td.appendChild(text); else td.textContent = text;
100 tr.appendChild(td);
101 return td;
102 }
103
104 function when (ms) { return ms ? new Date(ms).toLocaleString() : 'never'; }
105
106 async function loadGrants ()
107 {
108 const data = await call('GET', BASE + '/grants');
109 const tb = document.getElementById('grants');
110 tb.textContent = '';
111 if (!data.grants.length)
112 {
113 const tr = document.createElement('tr'); cell(tr, 'Nothing authorised yet.'); tb.appendChild(tr);
114 }
115 for (const g of data.grants)
116 {
117 const tr = document.createElement('tr');
118 cell(tr, g.name + (g.clientName && g.clientName !== g.name ? ' (' + g.clientName + ')' : ''));
119 cell(tr, g.kind === 'oauth' ? 'App / device' : 'Personal token');
120 cell(tr, g.scopes.includes('files:write') ? 'Read and write' : 'Read only');
121 cell(tr, when(g.lastUsedAt) + (g.lastUsedIp ? ' from ' + g.lastUsedIp : ''));
122 const btn = document.createElement('button');
123 btn.className = 'danger'; btn.textContent = 'Revoke';
124 btn.onclick = async () => { if (confirm('Revoke access for ' + g.name + '?')) { await call('DELETE', BASE + '/grants/' + encodeURIComponent(g.id)); loadGrants(); } };
125 cell(tr, btn);
126 tb.appendChild(tr);
127 }
128 }
129
130 async function loadClients ()
131 {
132 let data;
133 try { data = await call('GET', BASE + '/clients'); } catch { msg.textContent = ''; return; }
134 document.getElementById('clientsSection').hidden = false;
135 const tb = document.getElementById('clients');
136 tb.textContent = '';
137 for (const c of data.clients)
138 {
139 const tr = document.createElement('tr');
140 cell(tr, c.name);
141 const code = document.createElement('code'); code.textContent = c.clientId; cell(tr, code);
142 cell(tr, c.redirectUris.join(', '));
143 const btn = document.createElement('button');
144 btn.className = 'danger'; btn.textContent = 'Delete';
145 btn.onclick = async () => { if (confirm('Delete ' + c.name + '? All its grants are revoked.')) { await call('DELETE', BASE + '/clients/' + encodeURIComponent(c.clientId)); loadClients(); loadGrants(); } };
146 cell(tr, btn);
147 tb.appendChild(tr);
148 }
149 }
150
151 document.getElementById('revokeAll').onclick = async () =>
152 {
153 if (!confirm('Revoke access for every app, device and token?')) return;
154 await call('POST', BASE + '/grants/revoke-all');
155 loadGrants();
156 };
157
158 document.getElementById('patForm').onsubmit = async (e) =>
159 {
160 e.preventDefault();
161 const out = document.getElementById('patOut');
162 const data = await call('POST', BASE + '/tokens', {
163 name: document.getElementById('patName').value,
164 scopes: document.getElementById('patScope').value,
165 expiresInDays: document.getElementById('patDays').value || null,
166 });
167 out.textContent = 'Copy this token now, it is shown only once: ';
168 const code = document.createElement('code'); code.textContent = data.token; out.appendChild(code);
169 loadGrants();
170 };
171
172 document.getElementById('clientForm').onsubmit = async (e) =>
173 {
174 e.preventDefault();
175 await call('POST', BASE + '/clients', {
176 name: document.getElementById('clientName').value,
177 redirectUris: document.getElementById('clientUris').value.split(',').map((s) => s.trim()).filter(Boolean),
178 });
179 e.target.reset();
180 loadClients();
181 };
182
183 if (!token()) { msg.textContent = 'Please log in to the file manager first, then reload this page.'; return; }
184 loadGrants().then(loadClients).catch(() => {});
185})();
186</script>
187</body>
188</html>
server/api/manage.js added +81 −0
@@ -0,0 +1,81 @@
1 'use strict';
2
3 // Management of API access for logged-in web users (session auth):
4 // see and revoke connected apps/devices, create personal access tokens,
5 // and (admins) register OAuth clients.
6
7 const express = require('express');
8 const store = require('./store');
9 const { requireAuth, requireAdmin } = require('../auth');
10
11 const router = express.Router();
12 router.use(express.json({ limit: '32kb' }));
13 router.use(requireAuth);
14
15 router.get('/grants', (req, res) =>
16 {
17 res.json({ grants: store.listGrantsForUser(req.user.username), scopes: store.SCOPE_DESCRIPTIONS });
18 });
19
20 router.delete('/grants/:id', (req, res) =>
21 {
22 const g = store.getGrant(req.params.id);
23 if (!g || g.username !== req.user.username || g.revoked_at)
24 {
25 return res.status(404).json({ error: 'Not found.' });
26 }
27 store.revokeGrant(g.id);
28 res.json({ ok: true });
29 });
30
31 router.post('/grants/revoke-all', (req, res) =>
32 {
33 store.revokeAllForUser(req.user.username);
34 res.json({ ok: true });
35 });
36
37 router.post('/tokens', (req, res) =>
38 {
39 const body = req.body || {};
40 const name = String(body.name || '').trim().slice(0, 80);
41 if (!name) return res.status(400).json({ error: 'name is required.' });
42 const scopes = store.normalizeScopes(body.scopes || 'files:read');
43 if (!scopes || !scopes.length) return res.status(400).json({ error: `Allowed scopes: ${store.SCOPES.join(', ')}` });
44 let expiresAt = null;
45 if (body.expiresInDays != null && body.expiresInDays !== '')
46 {
47 const days = Number(body.expiresInDays);
48 if (!Number.isFinite(days) || days <= 0 || days > 3650) return res.status(400).json({ error: 'expiresInDays must be between 1 and 3650.' });
49 expiresAt = Date.now() + Math.round(days * 86400000);
50 }
51 const { id, token } = store.createPersonalToken({ username: req.user.username, name, scopes, expiresAt });
52 res.set('Cache-Control', 'no-store');
53 res.status(201).json({ id, token, scopes, expiresAt, note: 'Store this token now; it is not shown again.' });
54 });
55
56 router.get('/clients', requireAdmin, (req, res) =>
57 {
58 res.json({ clients: store.listClients().filter((c) => !c.disabled) });
59 });
60
61 router.post('/clients', requireAdmin, (req, res) =>
62 {
63 const body = req.body || {};
64 const name = String(body.name || '').trim().slice(0, 80);
65 const uris = Array.isArray(body.redirectUris) ? body.redirectUris.map((u) => String(u).trim()).filter(Boolean) : [];
66 if (!name) return res.status(400).json({ error: 'name is required.' });
67 if (!uris.length || uris.length > 10) return res.status(400).json({ error: 'Provide 1-10 redirectUris.' });
68 const bad = uris.find((u) => !store.validateRedirectUri(u));
69 if (bad) return res.status(400).json({ error: `Invalid redirect URI: ${bad}. Use https://, http://127.0.0.1 (loopback) or a private-use scheme like com.example.app:/callback.` });
70 res.status(201).json({ client: store.createClient({ name, redirectUris: uris, createdBy: req.user.username }) });
71 });
72
73 router.delete('/clients/:id', requireAdmin, (req, res) =>
74 {
75 const c = store.getClient(req.params.id);
76 if (!c || c.disabled) return res.status(404).json({ error: 'Not found.' });
77 store.deleteClient(c.clientId);
78 res.json({ ok: true });
79 });
80
81 module.exports = router;
@@ -0,0 +1,81 @@
1'use strict';
2
3// Management of API access for logged-in web users (session auth):
4// see and revoke connected apps/devices, create personal access tokens,
5// and (admins) register OAuth clients.
6
7const express = require('express');
8const store = require('./store');
9const { requireAuth, requireAdmin } = require('../auth');
10
11const router = express.Router();
12router.use(express.json({ limit: '32kb' }));
13router.use(requireAuth);
14
15router.get('/grants', (req, res) =>
16{
17 res.json({ grants: store.listGrantsForUser(req.user.username), scopes: store.SCOPE_DESCRIPTIONS });
18});
19
20router.delete('/grants/:id', (req, res) =>
21{
22 const g = store.getGrant(req.params.id);
23 if (!g || g.username !== req.user.username || g.revoked_at)
24 {
25 return res.status(404).json({ error: 'Not found.' });
26 }
27 store.revokeGrant(g.id);
28 res.json({ ok: true });
29});
30
31router.post('/grants/revoke-all', (req, res) =>
32{
33 store.revokeAllForUser(req.user.username);
34 res.json({ ok: true });
35});
36
37router.post('/tokens', (req, res) =>
38{
39 const body = req.body || {};
40 const name = String(body.name || '').trim().slice(0, 80);
41 if (!name) return res.status(400).json({ error: 'name is required.' });
42 const scopes = store.normalizeScopes(body.scopes || 'files:read');
43 if (!scopes || !scopes.length) return res.status(400).json({ error: `Allowed scopes: ${store.SCOPES.join(', ')}` });
44 let expiresAt = null;
45 if (body.expiresInDays != null && body.expiresInDays !== '')
46 {
47 const days = Number(body.expiresInDays);
48 if (!Number.isFinite(days) || days <= 0 || days > 3650) return res.status(400).json({ error: 'expiresInDays must be between 1 and 3650.' });
49 expiresAt = Date.now() + Math.round(days * 86400000);
50 }
51 const { id, token } = store.createPersonalToken({ username: req.user.username, name, scopes, expiresAt });
52 res.set('Cache-Control', 'no-store');
53 res.status(201).json({ id, token, scopes, expiresAt, note: 'Store this token now; it is not shown again.' });
54});
55
56router.get('/clients', requireAdmin, (req, res) =>
57{
58 res.json({ clients: store.listClients().filter((c) => !c.disabled) });
59});
60
61router.post('/clients', requireAdmin, (req, res) =>
62{
63 const body = req.body || {};
64 const name = String(body.name || '').trim().slice(0, 80);
65 const uris = Array.isArray(body.redirectUris) ? body.redirectUris.map((u) => String(u).trim()).filter(Boolean) : [];
66 if (!name) return res.status(400).json({ error: 'name is required.' });
67 if (!uris.length || uris.length > 10) return res.status(400).json({ error: 'Provide 1-10 redirectUris.' });
68 const bad = uris.find((u) => !store.validateRedirectUri(u));
69 if (bad) return res.status(400).json({ error: `Invalid redirect URI: ${bad}. Use https://, http://127.0.0.1 (loopback) or a private-use scheme like com.example.app:/callback.` });
70 res.status(201).json({ client: store.createClient({ name, redirectUris: uris, createdBy: req.user.username }) });
71});
72
73router.delete('/clients/:id', requireAdmin, (req, res) =>
74{
75 const c = store.getClient(req.params.id);
76 if (!c || c.disabled) return res.status(404).json({ error: 'Not found.' });
77 store.deleteClient(c.clientId);
78 res.json({ ok: true });
79});
80
81module.exports = router;
server/api/oauth.js added +319 −0
@@ -0,0 +1,319 @@
1 'use strict';
2
3 // OAuth 2.0 authorization server for the public API.
4 // Authorization code flow with mandatory PKCE (S256) for public clients
5 // (mobile/desktop/sync services; no client secrets), refresh token rotation,
6 // token revocation (RFC 7009) and server metadata (RFC 8414).
7
8 const express = require('express');
9 const bcrypt = require('bcrypt');
10 const store = require('./store');
11 const { getDb } = require('../db');
12 const { getClientIp } = require('../auth');
13
14 const router = express.Router();
15 const formParser = express.urlencoded({ extended: false, limit: '32kb' });
16 const jsonParser = express.json({ limit: '32kb' });
17
18 const LOGIN_FAIL_WINDOW_MS = 15 * 60 * 1000;
19 const LOGIN_FAIL_MAX = 10;
20 const loginFailures = new Map();
21
22 function issuer (req)
23 {
24 return `${req.protocol}://${req.get('host')}`;
25 }
26
27 function esc (v)
28 {
29 return String(v == null ? '' : v)
30 .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
31 .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
32 }
33
34 function noStore (res)
35 {
36 res.set('Cache-Control', 'no-store');
37 res.set('Pragma', 'no-cache');
38 }
39
40 function pageHeaders (res)
41 {
42 noStore(res);
43 res.set('X-Frame-Options', 'DENY');
44 res.set('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'");
45 res.set('Referrer-Policy', 'no-referrer');
46 }
47
48 function tooManyFailures (key)
49 {
50 const t = Date.now();
51 const list = (loginFailures.get(key) || []).filter((x) => t - x < LOGIN_FAIL_WINDOW_MS);
52 loginFailures.set(key, list);
53 return list.length >= LOGIN_FAIL_MAX;
54 }
55
56 function recordFailure (key)
57 {
58 const list = loginFailures.get(key) || [];
59 list.push(Date.now());
60 loginFailures.set(key, list);
61 if (loginFailures.size > 10000) loginFailures.clear();
62 }
63
64 function resetLoginFailures ()
65 {
66 loginFailures.clear();
67 }
68
69 /**
70 * Validates an authorization request. Returns { fatal } when we must NOT
71 * redirect (unknown client or redirect URI), { redirectError } for errors
72 * that go back to the client, or { request } when valid.
73 */
74 function parseAuthorizeRequest (params)
75 {
76 const clientId = String(params.client_id || '');
77 const redirectUri = String(params.redirect_uri || '');
78 const client = store.getClient(clientId);
79 if (!client || client.disabled) return { fatal: 'Unknown or disabled client_id.' };
80 if (!redirectUri || !store.redirectUriAllowed(client, redirectUri)) return { fatal: 'redirect_uri is not registered for this client.' };
81
82 const state = params.state != null ? String(params.state) : undefined;
83 const fail = (error, description) => ({ redirectError: { redirectUri, error, description, state } });
84
85 if (params.response_type !== 'code') return fail('unsupported_response_type', 'Only response_type=code is supported.');
86 const challenge = String(params.code_challenge || '');
87 if (!challenge) return fail('invalid_request', 'PKCE code_challenge is required.');
88 if (params.code_challenge_method !== 'S256') return fail('invalid_request', 'code_challenge_method must be S256.');
89 if (!/^[A-Za-z0-9_-]{43}$/.test(challenge)) return fail('invalid_request', 'Malformed code_challenge.');
90 const scopes = store.normalizeScopes(params.scope || 'files:read');
91 if (!scopes || !scopes.length) return fail('invalid_scope', `Allowed scopes: ${store.SCOPES.join(' ')}`);
92 const deviceName = String(params.device_name || '').trim().slice(0, 80) || client.name;
93
94 return { request: { client, clientId, redirectUri, state, scopes, codeChallenge: challenge, deviceName } };
95 }
96
97 function redirectWith (res, req, redirectUri, params)
98 {
99 const u = new URL(redirectUri);
100 for (const [k, v] of Object.entries(params))
101 {
102 if (v !== undefined && v !== null) u.searchParams.set(k, v);
103 }
104 u.searchParams.set('iss', issuer(req));
105 noStore(res);
106 return res.redirect(302, u.toString());
107 }
108
109 function renderError (res, status, message)
110 {
111 pageHeaders(res);
112 res.status(status).type('html').send(`<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Authorization error</title></head>
113 <body style="font-family:system-ui,sans-serif;max-width:32rem;margin:3rem auto;padding:0 1rem"><h1>Authorization error</h1><p>${esc(message)}</p></body></html>`);
114 }
115
116 function renderConsent (res, r, errorMessage, username)
117 {
118 pageHeaders(res);
119 const hidden = {
120 response_type: 'code',
121 client_id: r.clientId,
122 redirect_uri: r.redirectUri,
123 scope: r.scopes.join(' '),
124 state: r.state,
125 code_challenge: r.codeChallenge,
126 code_challenge_method: 'S256',
127 device_name: r.deviceName,
128 };
129 const hiddenHtml = Object.entries(hidden)
130 .filter(([, v]) => v !== undefined)
131 .map(([k, v]) => `<input type="hidden" name="${esc(k)}" value="${esc(v)}">`).join('\n');
132 const scopeHtml = r.scopes.map((s) => `<li><strong>${esc(s)}</strong>: ${esc(store.SCOPE_DESCRIPTIONS[s])}</li>`).join('');
133 let host = r.redirectUri;
134 try { host = new URL(r.redirectUri).host || r.redirectUri; } catch { /* keep */ }
135 res.status(errorMessage ? 401 : 200).type('html').send(`<!doctype html>
136 <html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
137 <title>Allow access to your files?</title>
138 <style>
139 body{font-family:system-ui,sans-serif;background:#f4f5f7;margin:0;padding:1rem}
140 main{max-width:28rem;margin:2rem auto;background:#fff;border-radius:10px;padding:1.5rem;box-shadow:0 1px 4px #0002}
141 label{display:block;margin:.6rem 0 .2rem}input[type=text],input[type=password]{width:100%;box-sizing:border-box;padding:.55rem;font-size:1rem}
142 .err{background:#fdecea;color:#8a1c12;padding:.5rem .75rem;border-radius:6px}.btns{display:flex;gap:.5rem;margin-top:1rem}
143 button{flex:1;padding:.65rem;font-size:1rem;border-radius:6px;border:1px solid #888;cursor:pointer}button.allow{background:#1f6feb;color:#fff;border-color:#1f6feb}
144 small{color:#555}
145 </style></head>
146 <body><main>
147 <h1 style="font-size:1.3rem">Allow <em>${esc(r.client.name)}</em> to access your files?</h1>
148 <p>Device: <strong>${esc(r.deviceName)}</strong><br><small>After approval you will be sent back to ${esc(host)}.</small></p>
149 <p>This app asks for:</p><ul>${scopeHtml}</ul>
150 <p><small>The app can never see more than you can. You can revoke access at any time on the <em>Connected apps</em> page (/apps.html).</small></p>
151 ${errorMessage ? `<p class="err">${esc(errorMessage)}</p>` : ''}
152 <form method="post" action="/oauth/authorize" autocomplete="on">
153 ${hiddenHtml}
154 <label for="u">Username</label><input id="u" type="text" name="username" autocomplete="username" value="${esc(username || '')}">
155 <label for="p">Password</label><input id="p" type="password" name="password" autocomplete="current-password">
156 <div class="btns"><button type="submit" name="decision" value="deny">Deny</button><button class="allow" type="submit" name="decision" value="allow">Allow</button></div>
157 </form></main></body></html>`);
158 }
159
160 router.get('/.well-known/oauth-authorization-server', (req, res) =>
161 {
162 const base = issuer(req);
163 res.json({
164 issuer: base,
165 authorization_endpoint: `${base}/oauth/authorize`,
166 token_endpoint: `${base}/oauth/token`,
167 revocation_endpoint: `${base}/oauth/revoke`,
168 scopes_supported: store.SCOPES,
169 response_types_supported: ['code'],
170 grant_types_supported: ['authorization_code', 'refresh_token'],
171 code_challenge_methods_supported: ['S256'],
172 token_endpoint_auth_methods_supported: ['none'],
173 authorization_response_iss_parameter_supported: true,
174 service_documentation: `${base}/api/v1/openapi.json`,
175 });
176 });
177
178 router.get('/oauth/authorize', (req, res) =>
179 {
180 const parsed = parseAuthorizeRequest(req.query);
181 if (parsed.fatal) return renderError(res, 400, parsed.fatal);
182 if (parsed.redirectError)
183 {
184 const e = parsed.redirectError;
185 return redirectWith(res, req, e.redirectUri, { error: e.error, error_description: e.description, state: e.state });
186 }
187 return renderConsent(res, parsed.request, null, '');
188 });
189
190 router.post('/oauth/authorize', formParser, async (req, res, next) =>
191 {
192 try
193 {
194 const body = req.body || {};
195 const parsed = parseAuthorizeRequest(body);
196 if (parsed.fatal) return renderError(res, 400, parsed.fatal);
197 if (parsed.redirectError)
198 {
199 const e = parsed.redirectError;
200 return redirectWith(res, req, e.redirectUri, { error: e.error, error_description: e.description, state: e.state });
201 }
202 const r = parsed.request;
203 if (body.decision !== 'allow')
204 {
205 return redirectWith(res, req, r.redirectUri, { error: 'access_denied', error_description: 'The user denied access.', state: r.state });
206 }
207
208 const username = String(body.username || '').trim();
209 const password = String(body.password || '');
210 const ip = getClientIp(req);
211 const failKey = `${ip}|${username.toLowerCase()}`;
212 if (tooManyFailures(failKey) || tooManyFailures(ip))
213 {
214 return renderConsent(res, r, 'Too many failed attempts. Try again later.', username);
215 }
216
217 const row = username ? getDb().prepare('SELECT username, password_hash FROM users WHERE username = ?').get([username]) : null;
218 const ok = row ? await bcrypt.compare(password, row.password_hash) : false;
219 if (!ok)
220 {
221 recordFailure(failKey);
222 recordFailure(ip);
223 return renderConsent(res, r, 'Invalid username or password.', username);
224 }
225
226 const code = store.createAuthCode({
227 clientId: r.clientId,
228 username: row.username,
229 redirectUri: r.redirectUri,
230 scopes: r.scopes,
231 codeChallenge: r.codeChallenge,
232 deviceName: r.deviceName,
233 });
234 return redirectWith(res, req, r.redirectUri, { code, state: r.state });
235 } catch (err)
236 {
237 next(err);
238 }
239 });
240
241 function tokenError (res, status, error, description)
242 {
243 noStore(res);
244 return res.status(status).json({ error, error_description: description });
245 }
246
247 function cors (req, res, next)
248 {
249 res.set('Access-Control-Allow-Origin', '*');
250 res.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');
251 res.set('Access-Control-Allow-Methods', 'POST, OPTIONS');
252 if (req.method === 'OPTIONS') return res.status(204).end();
253 next();
254 }
255
256 router.options('/oauth/token', cors);
257 router.options('/oauth/revoke', cors);
258
259 router.post('/oauth/token', cors, formParser, jsonParser, (req, res) =>
260 {
261 const body = req.body || {};
262 if (req.get('authorization')) return tokenError(res, 400, 'invalid_client', 'Clients are public; do not send client credentials.');
263 const clientId = String(body.client_id || '');
264 const client = store.getClient(clientId);
265 if (!client || client.disabled) return tokenError(res, 401, 'invalid_client', 'Unknown client_id.');
266
267 if (body.grant_type === 'authorization_code')
268 {
269 const row = store.consumeAuthCode(String(body.code || ''));
270 if (!row || row.client_id !== clientId) return tokenError(res, 400, 'invalid_grant', 'Invalid or expired code.');
271 if (String(body.redirect_uri || '') !== row.redirect_uri) return tokenError(res, 400, 'invalid_grant', 'redirect_uri mismatch.');
272 const verifier = String(body.code_verifier || '');
273 if (!/^[A-Za-z0-9._~-]{43,128}$/.test(verifier) || store.pkceS256(verifier) !== row.code_challenge)
274 {
275 return tokenError(res, 400, 'invalid_grant', 'PKCE verification failed.');
276 }
277 if (!store.userExists(row.username)) return tokenError(res, 400, 'invalid_grant', 'User no longer exists.');
278 const scopes = row.scopes.split(' ');
279 const grantId = store.createOAuthGrant({ username: row.username, clientId, name: row.device_name, scopes });
280 const t = store.issueTokensForGrant(grantId);
281 noStore(res);
282 return res.json({
283 access_token: t.accessToken,
284 token_type: 'Bearer',
285 expires_in: t.expiresIn,
286 refresh_token: t.refreshToken,
287 scope: scopes.join(' '),
288 grant_id: grantId,
289 });
290 }
291
292 if (body.grant_type === 'refresh_token')
293 {
294 const result = store.refreshGrant(clientId, String(body.refresh_token || ''));
295 if (result.error) return tokenError(res, 400, 'invalid_grant', 'Invalid, expired, reused or revoked refresh token.');
296 noStore(res);
297 return res.json({
298 access_token: result.tokens.accessToken,
299 token_type: 'Bearer',
300 expires_in: result.tokens.expiresIn,
301 refresh_token: result.tokens.refreshToken,
302 scope: result.grant.scopes,
303 grant_id: result.grant.id,
304 });
305 }
306
307 return tokenError(res, 400, 'unsupported_grant_type', 'Use authorization_code or refresh_token.');
308 });
309
310 router.post('/oauth/revoke', cors, formParser, jsonParser, (req, res) =>
311 {
312 const token = String((req.body && req.body.token) || '');
313 if (token) store.revokeByToken(token);
314 noStore(res);
315 res.status(200).json({});
316 });
317
318 router.resetLoginFailures = resetLoginFailures;
319 module.exports = router;
@@ -0,0 +1,319 @@
1'use strict';
2
3// OAuth 2.0 authorization server for the public API.
4// Authorization code flow with mandatory PKCE (S256) for public clients
5// (mobile/desktop/sync services; no client secrets), refresh token rotation,
6// token revocation (RFC 7009) and server metadata (RFC 8414).
7
8const express = require('express');
9const bcrypt = require('bcrypt');
10const store = require('./store');
11const { getDb } = require('../db');
12const { getClientIp } = require('../auth');
13
14const router = express.Router();
15const formParser = express.urlencoded({ extended: false, limit: '32kb' });
16const jsonParser = express.json({ limit: '32kb' });
17
18const LOGIN_FAIL_WINDOW_MS = 15 * 60 * 1000;
19const LOGIN_FAIL_MAX = 10;
20const loginFailures = new Map();
21
22function issuer (req)
23{
24 return `${req.protocol}://${req.get('host')}`;
25}
26
27function esc (v)
28{
29 return String(v == null ? '' : v)
30 .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
31 .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
32}
33
34function noStore (res)
35{
36 res.set('Cache-Control', 'no-store');
37 res.set('Pragma', 'no-cache');
38}
39
40function pageHeaders (res)
41{
42 noStore(res);
43 res.set('X-Frame-Options', 'DENY');
44 res.set('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'");
45 res.set('Referrer-Policy', 'no-referrer');
46}
47
48function tooManyFailures (key)
49{
50 const t = Date.now();
51 const list = (loginFailures.get(key) || []).filter((x) => t - x < LOGIN_FAIL_WINDOW_MS);
52 loginFailures.set(key, list);
53 return list.length >= LOGIN_FAIL_MAX;
54}
55
56function recordFailure (key)
57{
58 const list = loginFailures.get(key) || [];
59 list.push(Date.now());
60 loginFailures.set(key, list);
61 if (loginFailures.size > 10000) loginFailures.clear();
62}
63
64function resetLoginFailures ()
65{
66 loginFailures.clear();
67}
68
69/**
70 * Validates an authorization request. Returns { fatal } when we must NOT
71 * redirect (unknown client or redirect URI), { redirectError } for errors
72 * that go back to the client, or { request } when valid.
73 */
74function parseAuthorizeRequest (params)
75{
76 const clientId = String(params.client_id || '');
77 const redirectUri = String(params.redirect_uri || '');
78 const client = store.getClient(clientId);
79 if (!client || client.disabled) return { fatal: 'Unknown or disabled client_id.' };
80 if (!redirectUri || !store.redirectUriAllowed(client, redirectUri)) return { fatal: 'redirect_uri is not registered for this client.' };
81
82 const state = params.state != null ? String(params.state) : undefined;
83 const fail = (error, description) => ({ redirectError: { redirectUri, error, description, state } });
84
85 if (params.response_type !== 'code') return fail('unsupported_response_type', 'Only response_type=code is supported.');
86 const challenge = String(params.code_challenge || '');
87 if (!challenge) return fail('invalid_request', 'PKCE code_challenge is required.');
88 if (params.code_challenge_method !== 'S256') return fail('invalid_request', 'code_challenge_method must be S256.');
89 if (!/^[A-Za-z0-9_-]{43}$/.test(challenge)) return fail('invalid_request', 'Malformed code_challenge.');
90 const scopes = store.normalizeScopes(params.scope || 'files:read');
91 if (!scopes || !scopes.length) return fail('invalid_scope', `Allowed scopes: ${store.SCOPES.join(' ')}`);
92 const deviceName = String(params.device_name || '').trim().slice(0, 80) || client.name;
93
94 return { request: { client, clientId, redirectUri, state, scopes, codeChallenge: challenge, deviceName } };
95}
96
97function redirectWith (res, req, redirectUri, params)
98{
99 const u = new URL(redirectUri);
100 for (const [k, v] of Object.entries(params))
101 {
102 if (v !== undefined && v !== null) u.searchParams.set(k, v);
103 }
104 u.searchParams.set('iss', issuer(req));
105 noStore(res);
106 return res.redirect(302, u.toString());
107}
108
109function renderError (res, status, message)
110{
111 pageHeaders(res);
112 res.status(status).type('html').send(`<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Authorization error</title></head>
113<body style="font-family:system-ui,sans-serif;max-width:32rem;margin:3rem auto;padding:0 1rem"><h1>Authorization error</h1><p>${esc(message)}</p></body></html>`);
114}
115
116function renderConsent (res, r, errorMessage, username)
117{
118 pageHeaders(res);
119 const hidden = {
120 response_type: 'code',
121 client_id: r.clientId,
122 redirect_uri: r.redirectUri,
123 scope: r.scopes.join(' '),
124 state: r.state,
125 code_challenge: r.codeChallenge,
126 code_challenge_method: 'S256',
127 device_name: r.deviceName,
128 };
129 const hiddenHtml = Object.entries(hidden)
130 .filter(([, v]) => v !== undefined)
131 .map(([k, v]) => `<input type="hidden" name="${esc(k)}" value="${esc(v)}">`).join('\n');
132 const scopeHtml = r.scopes.map((s) => `<li><strong>${esc(s)}</strong>: ${esc(store.SCOPE_DESCRIPTIONS[s])}</li>`).join('');
133 let host = r.redirectUri;
134 try { host = new URL(r.redirectUri).host || r.redirectUri; } catch { /* keep */ }
135 res.status(errorMessage ? 401 : 200).type('html').send(`<!doctype html>
136<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
137<title>Allow access to your files?</title>
138<style>
139body{font-family:system-ui,sans-serif;background:#f4f5f7;margin:0;padding:1rem}
140main{max-width:28rem;margin:2rem auto;background:#fff;border-radius:10px;padding:1.5rem;box-shadow:0 1px 4px #0002}
141label{display:block;margin:.6rem 0 .2rem}input[type=text],input[type=password]{width:100%;box-sizing:border-box;padding:.55rem;font-size:1rem}
142.err{background:#fdecea;color:#8a1c12;padding:.5rem .75rem;border-radius:6px}.btns{display:flex;gap:.5rem;margin-top:1rem}
143button{flex:1;padding:.65rem;font-size:1rem;border-radius:6px;border:1px solid #888;cursor:pointer}button.allow{background:#1f6feb;color:#fff;border-color:#1f6feb}
144small{color:#555}
145</style></head>
146<body><main>
147<h1 style="font-size:1.3rem">Allow <em>${esc(r.client.name)}</em> to access your files?</h1>
148<p>Device: <strong>${esc(r.deviceName)}</strong><br><small>After approval you will be sent back to ${esc(host)}.</small></p>
149<p>This app asks for:</p><ul>${scopeHtml}</ul>
150<p><small>The app can never see more than you can. You can revoke access at any time on the <em>Connected apps</em> page (/apps.html).</small></p>
151${errorMessage ? `<p class="err">${esc(errorMessage)}</p>` : ''}
152<form method="post" action="/oauth/authorize" autocomplete="on">
153${hiddenHtml}
154<label for="u">Username</label><input id="u" type="text" name="username" autocomplete="username" value="${esc(username || '')}">
155<label for="p">Password</label><input id="p" type="password" name="password" autocomplete="current-password">
156<div class="btns"><button type="submit" name="decision" value="deny">Deny</button><button class="allow" type="submit" name="decision" value="allow">Allow</button></div>
157</form></main></body></html>`);
158}
159
160router.get('/.well-known/oauth-authorization-server', (req, res) =>
161{
162 const base = issuer(req);
163 res.json({
164 issuer: base,
165 authorization_endpoint: `${base}/oauth/authorize`,
166 token_endpoint: `${base}/oauth/token`,
167 revocation_endpoint: `${base}/oauth/revoke`,
168 scopes_supported: store.SCOPES,
169 response_types_supported: ['code'],
170 grant_types_supported: ['authorization_code', 'refresh_token'],
171 code_challenge_methods_supported: ['S256'],
172 token_endpoint_auth_methods_supported: ['none'],
173 authorization_response_iss_parameter_supported: true,
174 service_documentation: `${base}/api/v1/openapi.json`,
175 });
176});
177
178router.get('/oauth/authorize', (req, res) =>
179{
180 const parsed = parseAuthorizeRequest(req.query);
181 if (parsed.fatal) return renderError(res, 400, parsed.fatal);
182 if (parsed.redirectError)
183 {
184 const e = parsed.redirectError;
185 return redirectWith(res, req, e.redirectUri, { error: e.error, error_description: e.description, state: e.state });
186 }
187 return renderConsent(res, parsed.request, null, '');
188});
189
190router.post('/oauth/authorize', formParser, async (req, res, next) =>
191{
192 try
193 {
194 const body = req.body || {};
195 const parsed = parseAuthorizeRequest(body);
196 if (parsed.fatal) return renderError(res, 400, parsed.fatal);
197 if (parsed.redirectError)
198 {
199 const e = parsed.redirectError;
200 return redirectWith(res, req, e.redirectUri, { error: e.error, error_description: e.description, state: e.state });
201 }
202 const r = parsed.request;
203 if (body.decision !== 'allow')
204 {
205 return redirectWith(res, req, r.redirectUri, { error: 'access_denied', error_description: 'The user denied access.', state: r.state });
206 }
207
208 const username = String(body.username || '').trim();
209 const password = String(body.password || '');
210 const ip = getClientIp(req);
211 const failKey = `${ip}|${username.toLowerCase()}`;
212 if (tooManyFailures(failKey) || tooManyFailures(ip))
213 {
214 return renderConsent(res, r, 'Too many failed attempts. Try again later.', username);
215 }
216
217 const row = username ? getDb().prepare('SELECT username, password_hash FROM users WHERE username = ?').get([username]) : null;
218 const ok = row ? await bcrypt.compare(password, row.password_hash) : false;
219 if (!ok)
220 {
221 recordFailure(failKey);
222 recordFailure(ip);
223 return renderConsent(res, r, 'Invalid username or password.', username);
224 }
225
226 const code = store.createAuthCode({
227 clientId: r.clientId,
228 username: row.username,
229 redirectUri: r.redirectUri,
230 scopes: r.scopes,
231 codeChallenge: r.codeChallenge,
232 deviceName: r.deviceName,
233 });
234 return redirectWith(res, req, r.redirectUri, { code, state: r.state });
235 } catch (err)
236 {
237 next(err);
238 }
239});
240
241function tokenError (res, status, error, description)
242{
243 noStore(res);
244 return res.status(status).json({ error, error_description: description });
245}
246
247function cors (req, res, next)
248{
249 res.set('Access-Control-Allow-Origin', '*');
250 res.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');
251 res.set('Access-Control-Allow-Methods', 'POST, OPTIONS');
252 if (req.method === 'OPTIONS') return res.status(204).end();
253 next();
254}
255
256router.options('/oauth/token', cors);
257router.options('/oauth/revoke', cors);
258
259router.post('/oauth/token', cors, formParser, jsonParser, (req, res) =>
260{
261 const body = req.body || {};
262 if (req.get('authorization')) return tokenError(res, 400, 'invalid_client', 'Clients are public; do not send client credentials.');
263 const clientId = String(body.client_id || '');
264 const client = store.getClient(clientId);
265 if (!client || client.disabled) return tokenError(res, 401, 'invalid_client', 'Unknown client_id.');
266
267 if (body.grant_type === 'authorization_code')
268 {
269 const row = store.consumeAuthCode(String(body.code || ''));
270 if (!row || row.client_id !== clientId) return tokenError(res, 400, 'invalid_grant', 'Invalid or expired code.');
271 if (String(body.redirect_uri || '') !== row.redirect_uri) return tokenError(res, 400, 'invalid_grant', 'redirect_uri mismatch.');
272 const verifier = String(body.code_verifier || '');
273 if (!/^[A-Za-z0-9._~-]{43,128}$/.test(verifier) || store.pkceS256(verifier) !== row.code_challenge)
274 {
275 return tokenError(res, 400, 'invalid_grant', 'PKCE verification failed.');
276 }
277 if (!store.userExists(row.username)) return tokenError(res, 400, 'invalid_grant', 'User no longer exists.');
278 const scopes = row.scopes.split(' ');
279 const grantId = store.createOAuthGrant({ username: row.username, clientId, name: row.device_name, scopes });
280 const t = store.issueTokensForGrant(grantId);
281 noStore(res);
282 return res.json({
283 access_token: t.accessToken,
284 token_type: 'Bearer',
285 expires_in: t.expiresIn,
286 refresh_token: t.refreshToken,
287 scope: scopes.join(' '),
288 grant_id: grantId,
289 });
290 }
291
292 if (body.grant_type === 'refresh_token')
293 {
294 const result = store.refreshGrant(clientId, String(body.refresh_token || ''));
295 if (result.error) return tokenError(res, 400, 'invalid_grant', 'Invalid, expired, reused or revoked refresh token.');
296 noStore(res);
297 return res.json({
298 access_token: result.tokens.accessToken,
299 token_type: 'Bearer',
300 expires_in: result.tokens.expiresIn,
301 refresh_token: result.tokens.refreshToken,
302 scope: result.grant.scopes,
303 grant_id: result.grant.id,
304 });
305 }
306
307 return tokenError(res, 400, 'unsupported_grant_type', 'Use authorization_code or refresh_token.');
308});
309
310router.post('/oauth/revoke', cors, formParser, jsonParser, (req, res) =>
311{
312 const token = String((req.body && req.body.token) || '');
313 if (token) store.revokeByToken(token);
314 noStore(res);
315 res.status(200).json({});
316});
317
318router.resetLoginFailures = resetLoginFailures;
319module.exports = router;
server/api/store.js added +457 −0
@@ -0,0 +1,457 @@
1 'use strict';
2
3 // Storage for the public API: OAuth clients, grants (one per authorised
4 // app/device or personal token), access tokens and authorization codes.
5 // Secrets are only ever stored as SHA-256 hashes.
6
7 const crypto = require('crypto');
8 const { getDb } = require('../db');
9
10 const ACCESS_TOKEN_TTL_MS = 60 * 60 * 1000; // 1 hour
11 const REFRESH_TOKEN_TTL_MS = 90 * 24 * 60 * 60 * 1000; // 90 days, sliding
12 const AUTH_CODE_TTL_MS = 10 * 60 * 1000;
13
14 const SCOPES = ['files:read', 'files:write'];
15 const SCOPE_DESCRIPTIONS = {
16 'files:read': 'List, read and download your files (everything you can see yourself)',
17 'files:write': 'Upload, create, rename, move and delete files and folders you can change yourself',
18 };
19
20 function initApiSchema (d)
21 {
22 d.exec(`
23 CREATE TABLE IF NOT EXISTS api_clients (
24 client_id TEXT PRIMARY KEY,
25 name TEXT NOT NULL,
26 redirect_uris TEXT NOT NULL DEFAULT '[]',
27 created_by TEXT NOT NULL,
28 created_at INTEGER NOT NULL,
29 disabled_at INTEGER
30 );
31
32 CREATE TABLE IF NOT EXISTS api_grants (
33 id TEXT PRIMARY KEY,
34 username TEXT NOT NULL,
35 kind TEXT NOT NULL,
36 client_id TEXT,
37 name TEXT NOT NULL,
38 scopes TEXT NOT NULL,
39 created_at INTEGER NOT NULL,
40 last_used_at INTEGER,
41 last_used_ip TEXT,
42 expires_at INTEGER,
43 revoked_at INTEGER,
44 secret_hash TEXT,
45 refresh_hash TEXT,
46 refresh_expires_at INTEGER,
47 prev_refresh_hash TEXT
48 );
49 CREATE INDEX IF NOT EXISTS idx_api_grants_username ON api_grants(username);
50 CREATE UNIQUE INDEX IF NOT EXISTS idx_api_grants_secret ON api_grants(secret_hash);
51 CREATE UNIQUE INDEX IF NOT EXISTS idx_api_grants_refresh ON api_grants(refresh_hash);
52 CREATE INDEX IF NOT EXISTS idx_api_grants_prev_refresh ON api_grants(prev_refresh_hash);
53
54 CREATE TABLE IF NOT EXISTS api_access_tokens (
55 token_hash TEXT PRIMARY KEY,
56 grant_id TEXT NOT NULL,
57 expires_at INTEGER NOT NULL
58 );
59 CREATE INDEX IF NOT EXISTS idx_api_access_tokens_grant ON api_access_tokens(grant_id);
60
61 CREATE TABLE IF NOT EXISTS api_auth_codes (
62 code_hash TEXT PRIMARY KEY,
63 client_id TEXT NOT NULL,
64 username TEXT NOT NULL,
65 redirect_uri TEXT NOT NULL,
66 scopes TEXT NOT NULL,
67 code_challenge TEXT NOT NULL,
68 device_name TEXT NOT NULL,
69 expires_at INTEGER NOT NULL
70 );
71
72 CREATE TABLE IF NOT EXISTS api_entries (
73 root_key TEXT NOT NULL,
74 rel_path TEXT NOT NULL,
75 file_id TEXT NOT NULL,
76 is_dir INTEGER NOT NULL,
77 size INTEGER NOT NULL,
78 mtime_ms INTEGER NOT NULL,
79 version TEXT NOT NULL,
80 PRIMARY KEY (root_key, rel_path)
81 );
82
83 CREATE TABLE IF NOT EXISTS api_changes (
84 seq INTEGER PRIMARY KEY AUTOINCREMENT,
85 root_key TEXT NOT NULL,
86 change TEXT NOT NULL,
87 rel_path TEXT NOT NULL,
88 old_rel_path TEXT,
89 file_id TEXT NOT NULL,
90 is_dir INTEGER NOT NULL,
91 size INTEGER,
92 mtime_ms INTEGER,
93 version TEXT,
94 at INTEGER NOT NULL
95 );
96 CREATE INDEX IF NOT EXISTS idx_api_changes_root ON api_changes(root_key, seq);
97
98 CREATE TABLE IF NOT EXISTS api_scan_state (
99 root_key TEXT PRIMARY KEY,
100 generation TEXT NOT NULL,
101 last_scan_at INTEGER NOT NULL DEFAULT 0,
102 dirty INTEGER NOT NULL DEFAULT 1,
103 min_seq INTEGER NOT NULL DEFAULT 0
104 );
105
106 CREATE TABLE IF NOT EXISTS api_hashes (
107 abs_path TEXT PRIMARY KEY,
108 size INTEGER NOT NULL,
109 mtime_ms INTEGER NOT NULL,
110 sha256 TEXT NOT NULL
111 );
112
113 CREATE TABLE IF NOT EXISTS api_uploads (
114 id TEXT PRIMARY KEY,
115 grant_id TEXT NOT NULL,
116 username TEXT NOT NULL,
117 target TEXT NOT NULL,
118 size INTEGER NOT NULL,
119 received INTEGER NOT NULL DEFAULT 0,
120 sha256 TEXT,
121 mtime_ms INTEGER,
122 if_match TEXT,
123 if_none_match INTEGER NOT NULL DEFAULT 0,
124 overwrite INTEGER NOT NULL DEFAULT 0,
125 created_at INTEGER NOT NULL,
126 expires_at INTEGER NOT NULL
127 );
128 `);
129 }
130
131 function sha256Hex (value)
132 {
133 return crypto.createHash('sha256').update(String(value)).digest('hex');
134 }
135
136 function randomToken (prefix, bytes = 32)
137 {
138 return prefix + crypto.randomBytes(bytes).toString('base64url');
139 }
140
141 function now ()
142 {
143 return Date.now();
144 }
145
146 function normalizeScopes (raw)
147 {
148 const list = Array.isArray(raw) ? raw : String(raw || '').split(/[\s,]+/);
149 const out = [];
150 for (const s of list)
151 {
152 const v = String(s || '').trim();
153 if (!v) continue;
154 if (!SCOPES.includes(v)) return null;
155 if (!out.includes(v)) out.push(v);
156 }
157 // Write implies read: a sync client must see what it changes.
158 if (out.includes('files:write') && !out.includes('files:read')) out.unshift('files:read');
159 return out;
160 }
161
162 // ---------------------------------------------------------------------------
163 // Clients
164 // ---------------------------------------------------------------------------
165
166 function parseClient (row)
167 {
168 if (!row) return null;
169 let uris = [];
170 try { uris = JSON.parse(row.redirect_uris || '[]'); } catch { uris = []; }
171 return {
172 clientId: row.client_id,
173 name: row.name,
174 redirectUris: Array.isArray(uris) ? uris : [],
175 createdBy: row.created_by,
176 createdAt: row.created_at,
177 disabled: !!row.disabled_at,
178 };
179 }
180
181 function validateRedirectUri (uri)
182 {
183 let u;
184 try { u = new URL(String(uri)); } catch { return false; }
185 if (u.hash) return false;
186 if (u.protocol === 'https:') return true;
187 if (u.protocol === 'http:') return u.hostname === '127.0.0.1' || u.hostname === '[::1]' || u.hostname === 'localhost';
188 // Private-use URI scheme for mobile/desktop apps (RFC 8252 7.1), e.g. com.example.app:/cb
189 return /^[a-z][a-z0-9+.-]*\.[a-z0-9+.-]+:$/i.test(u.protocol);
190 }
191
192 function createClient ({ name, redirectUris, createdBy })
193 {
194 const clientId = 'fmc_' + crypto.randomBytes(12).toString('base64url');
195 getDb().prepare('INSERT INTO api_clients (client_id, name, redirect_uris, created_by, created_at) VALUES (?, ?, ?, ?, ?)')
196 .run([clientId, name, JSON.stringify(redirectUris), createdBy, now()]);
197 return getClient(clientId);
198 }
199
200 function getClient (clientId)
201 {
202 return parseClient(getDb().prepare('SELECT * FROM api_clients WHERE client_id = ?').get([String(clientId || '')]));
203 }
204
205 function listClients ()
206 {
207 return getDb().prepare('SELECT * FROM api_clients ORDER BY created_at').all().map(parseClient);
208 }
209
210 function deleteClient (clientId)
211 {
212 const d = getDb();
213 d.prepare('UPDATE api_clients SET disabled_at = ? WHERE client_id = ? AND disabled_at IS NULL').run([now(), clientId]);
214 const grants = d.prepare('SELECT id FROM api_grants WHERE client_id = ? AND revoked_at IS NULL').all([clientId]);
215 for (const g of grants) revokeGrant(g.id);
216 }
217
218 /**
219 * RFC 8252 7.3: for loopback redirects the port may vary at request time.
220 */
221 function redirectUriAllowed (client, uri)
222 {
223 if (!client || !uri) return false;
224 if (client.redirectUris.includes(uri)) return true;
225 let req;
226 try { req = new URL(uri); } catch { return false; }
227 if (req.protocol !== 'http:' || !['127.0.0.1', '[::1]', 'localhost'].includes(req.hostname)) return false;
228 return client.redirectUris.some((reg) =>
229 {
230 try
231 {
232 const r = new URL(reg);
233 return r.protocol === 'http:' && r.hostname === req.hostname && r.pathname === req.pathname;
234 } catch { return false; }
235 });
236 }
237
238 // ---------------------------------------------------------------------------
239 // Authorization codes
240 // ---------------------------------------------------------------------------
241
242 function createAuthCode ({ clientId, username, redirectUri, scopes, codeChallenge, deviceName })
243 {
244 const code = randomToken('fmo_');
245 const d = getDb();
246 d.prepare('DELETE FROM api_auth_codes WHERE expires_at < ?').run([now()]);
247 d.prepare(`INSERT INTO api_auth_codes (code_hash, client_id, username, redirect_uri, scopes, code_challenge, device_name, expires_at)
248 VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
249 .run([sha256Hex(code), clientId, username, redirectUri, scopes.join(' '), codeChallenge, deviceName, now() + AUTH_CODE_TTL_MS]);
250 return code;
251 }
252
253 /** Single use: the row is deleted whether or not the exchange succeeds. */
254 function consumeAuthCode (code)
255 {
256 const d = getDb();
257 const hash = sha256Hex(code || '');
258 const row = d.prepare('SELECT * FROM api_auth_codes WHERE code_hash = ?').get([hash]);
259 if (!row) return null;
260 d.prepare('DELETE FROM api_auth_codes WHERE code_hash = ?').run([hash]);
261 if (row.expires_at < now()) return null;
262 return row;
263 }
264
265 function pkceS256 (verifier)
266 {
267 return crypto.createHash('sha256').update(String(verifier)).digest('base64url');
268 }
269
270 // ---------------------------------------------------------------------------
271 // Grants and tokens
272 // ---------------------------------------------------------------------------
273
274 function issueTokensForGrant (grantId)
275 {
276 const d = getDb();
277 const accessToken = randomToken('fma_');
278 const refreshToken = randomToken('fmr_');
279 const t = now();
280 d.prepare('DELETE FROM api_access_tokens WHERE expires_at < ?').run([t]);
281 d.prepare('INSERT INTO api_access_tokens (token_hash, grant_id, expires_at) VALUES (?, ?, ?)')
282 .run([sha256Hex(accessToken), grantId, t + ACCESS_TOKEN_TTL_MS]);
283 const g = d.prepare('SELECT refresh_hash FROM api_grants WHERE id = ?').get([grantId]);
284 d.prepare('UPDATE api_grants SET prev_refresh_hash = ?, refresh_hash = ?, refresh_expires_at = ? WHERE id = ?')
285 .run([g ? g.refresh_hash : null, sha256Hex(refreshToken), t + REFRESH_TOKEN_TTL_MS, grantId]);
286 return { accessToken, refreshToken, expiresIn: Math.floor(ACCESS_TOKEN_TTL_MS / 1000) };
287 }
288
289 function createOAuthGrant ({ username, clientId, name, scopes })
290 {
291 const id = 'g_' + crypto.randomBytes(12).toString('base64url');
292 getDb().prepare('INSERT INTO api_grants (id, username, kind, client_id, name, scopes, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)')
293 .run([id, username, 'oauth', clientId, name, scopes.join(' '), now()]);
294 return id;
295 }
296
297 function createPersonalToken ({ username, name, scopes, expiresAt })
298 {
299 const id = 'g_' + crypto.randomBytes(12).toString('base64url');
300 const token = randomToken('fmp_');
301 getDb().prepare('INSERT INTO api_grants (id, username, kind, client_id, name, scopes, created_at, expires_at, secret_hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)')
302 .run([id, username, 'personal', null, name, scopes.join(' '), now(), expiresAt || null, sha256Hex(token)]);
303 return { id, token };
304 }
305
306 function getGrant (id)
307 {
308 return getDb().prepare('SELECT * FROM api_grants WHERE id = ?').get([String(id || '')]) || null;
309 }
310
311 /**
312 * Refresh token rotation with reuse detection: presenting an already rotated
313 * refresh token revokes the whole grant (it was probably stolen).
314 */
315 function refreshGrant (clientId, refreshToken)
316 {
317 const d = getDb();
318 const hash = sha256Hex(refreshToken || '');
319 const g = d.prepare('SELECT * FROM api_grants WHERE refresh_hash = ?').get([hash]);
320 if (!g)
321 {
322 const reused = d.prepare('SELECT id FROM api_grants WHERE prev_refresh_hash = ?').get([hash]);
323 if (reused) revokeGrant(reused.id);
324 return { error: 'invalid_grant' };
325 }
326 if (g.revoked_at || g.client_id !== clientId || !g.refresh_expires_at || g.refresh_expires_at < now())
327 {
328 return { error: 'invalid_grant' };
329 }
330 const client = getClient(g.client_id);
331 if (!client || client.disabled) return { error: 'invalid_grant' };
332 if (!userExists(g.username)) return { error: 'invalid_grant' };
333 return { grant: g, tokens: issueTokensForGrant(g.id) };
334 }
335
336 function revokeGrant (id)
337 {
338 const d = getDb();
339 d.prepare('UPDATE api_grants SET revoked_at = ?, refresh_hash = NULL, prev_refresh_hash = NULL, secret_hash = NULL WHERE id = ? AND revoked_at IS NULL')
340 .run([now(), id]);
341 d.prepare('DELETE FROM api_access_tokens WHERE grant_id = ?').run([id]);
342 d.prepare('DELETE FROM api_uploads WHERE grant_id = ?').run([id]);
343 }
344
345 function revokeAllForUser (username)
346 {
347 const rows = getDb().prepare('SELECT id FROM api_grants WHERE username = ? AND revoked_at IS NULL').all([username]);
348 for (const r of rows) revokeGrant(r.id);
349 }
350
351 /** Revoke by presenting either the access or the refresh token (RFC 7009). */
352 function revokeByToken (token)
353 {
354 const d = getDb();
355 const hash = sha256Hex(token || '');
356 const at = d.prepare('SELECT grant_id FROM api_access_tokens WHERE token_hash = ?').get([hash]);
357 if (at) { revokeGrant(at.grant_id); return true; }
358 const g = d.prepare('SELECT id FROM api_grants WHERE refresh_hash = ? OR secret_hash = ?').get([hash, hash]);
359 if (g) { revokeGrant(g.id); return true; }
360 return false;
361 }
362
363 function userExists (username)
364 {
365 return !!getDb().prepare('SELECT 1 AS ok FROM users WHERE username = ?').get([username]);
366 }
367
368 /**
369 * Resolve a bearer token to { grant, scopes }. Returns null when the token is
370 * unknown, expired or revoked.
371 */
372 function resolveBearer (token)
373 {
374 const t = String(token || '');
375 if (!t) return null;
376 const d = getDb();
377 const hash = sha256Hex(t);
378 let grant = null;
379 if (t.startsWith('fma_'))
380 {
381 const row = d.prepare('SELECT grant_id, expires_at FROM api_access_tokens WHERE token_hash = ?').get([hash]);
382 if (!row || row.expires_at < now()) return null;
383 grant = getGrant(row.grant_id);
384 } else if (t.startsWith('fmp_'))
385 {
386 grant = d.prepare('SELECT * FROM api_grants WHERE secret_hash = ?').get([hash]) || null;
387 if (grant && grant.expires_at && grant.expires_at < now()) return null;
388 }
389 if (!grant || grant.revoked_at) return null;
390 if (grant.kind === 'oauth')
391 {
392 const client = getClient(grant.client_id);
393 if (!client || client.disabled) return null;
394 }
395 return { grant, scopes: String(grant.scopes || '').split(' ').filter(Boolean) };
396 }
397
398 function touchGrant (id, ip)
399 {
400 const g = getGrant(id);
401 if (!g) return;
402 const t = now();
403 if (!g.last_used_at || t - g.last_used_at > 60 * 1000 || g.last_used_ip !== ip)
404 {
405 getDb().prepare('UPDATE api_grants SET last_used_at = ?, last_used_ip = ? WHERE id = ?').run([t, ip, id]);
406 }
407 }
408
409 function listGrantsForUser (username)
410 {
411 return getDb().prepare(`SELECT g.*, c.name AS client_name FROM api_grants g LEFT JOIN api_clients c ON c.client_id = g.client_id
412 WHERE g.username = ? AND g.revoked_at IS NULL ORDER BY g.created_at DESC`)
413 .all([username])
414 .map((g) => ({
415 id: g.id,
416 kind: g.kind,
417 name: g.name,
418 clientId: g.client_id,
419 clientName: g.client_name || null,
420 scopes: String(g.scopes || '').split(' ').filter(Boolean),
421 createdAt: g.created_at,
422 lastUsedAt: g.last_used_at,
423 lastUsedIp: g.last_used_ip,
424 expiresAt: g.expires_at || (g.kind === 'oauth' ? g.refresh_expires_at : null),
425 }));
426 }
427
428 module.exports = {
429 SCOPES,
430 SCOPE_DESCRIPTIONS,
431 ACCESS_TOKEN_TTL_MS,
432 REFRESH_TOKEN_TTL_MS,
433 initApiSchema,
434 sha256Hex,
435 normalizeScopes,
436 validateRedirectUri,
437 createClient,
438 getClient,
439 listClients,
440 deleteClient,
441 redirectUriAllowed,
442 createAuthCode,
443 consumeAuthCode,
444 pkceS256,
445 createOAuthGrant,
446 createPersonalToken,
447 issueTokensForGrant,
448 refreshGrant,
449 revokeGrant,
450 revokeAllForUser,
451 revokeByToken,
452 resolveBearer,
453 touchGrant,
454 getGrant,
455 listGrantsForUser,
456 userExists,
457 };
@@ -0,0 +1,457 @@
1'use strict';
2
3// Storage for the public API: OAuth clients, grants (one per authorised
4// app/device or personal token), access tokens and authorization codes.
5// Secrets are only ever stored as SHA-256 hashes.
6
7const crypto = require('crypto');
8const { getDb } = require('../db');
9
10const ACCESS_TOKEN_TTL_MS = 60 * 60 * 1000; // 1 hour
11const REFRESH_TOKEN_TTL_MS = 90 * 24 * 60 * 60 * 1000; // 90 days, sliding
12const AUTH_CODE_TTL_MS = 10 * 60 * 1000;
13
14const SCOPES = ['files:read', 'files:write'];
15const SCOPE_DESCRIPTIONS = {
16 'files:read': 'List, read and download your files (everything you can see yourself)',
17 'files:write': 'Upload, create, rename, move and delete files and folders you can change yourself',
18};
19
20function initApiSchema (d)
21{
22 d.exec(`
23 CREATE TABLE IF NOT EXISTS api_clients (
24 client_id TEXT PRIMARY KEY,
25 name TEXT NOT NULL,
26 redirect_uris TEXT NOT NULL DEFAULT '[]',
27 created_by TEXT NOT NULL,
28 created_at INTEGER NOT NULL,
29 disabled_at INTEGER
30 );
31
32 CREATE TABLE IF NOT EXISTS api_grants (
33 id TEXT PRIMARY KEY,
34 username TEXT NOT NULL,
35 kind TEXT NOT NULL,
36 client_id TEXT,
37 name TEXT NOT NULL,
38 scopes TEXT NOT NULL,
39 created_at INTEGER NOT NULL,
40 last_used_at INTEGER,
41 last_used_ip TEXT,
42 expires_at INTEGER,
43 revoked_at INTEGER,
44 secret_hash TEXT,
45 refresh_hash TEXT,
46 refresh_expires_at INTEGER,
47 prev_refresh_hash TEXT
48 );
49 CREATE INDEX IF NOT EXISTS idx_api_grants_username ON api_grants(username);
50 CREATE UNIQUE INDEX IF NOT EXISTS idx_api_grants_secret ON api_grants(secret_hash);
51 CREATE UNIQUE INDEX IF NOT EXISTS idx_api_grants_refresh ON api_grants(refresh_hash);
52 CREATE INDEX IF NOT EXISTS idx_api_grants_prev_refresh ON api_grants(prev_refresh_hash);
53
54 CREATE TABLE IF NOT EXISTS api_access_tokens (
55 token_hash TEXT PRIMARY KEY,
56 grant_id TEXT NOT NULL,
57 expires_at INTEGER NOT NULL
58 );
59 CREATE INDEX IF NOT EXISTS idx_api_access_tokens_grant ON api_access_tokens(grant_id);
60
61 CREATE TABLE IF NOT EXISTS api_auth_codes (
62 code_hash TEXT PRIMARY KEY,
63 client_id TEXT NOT NULL,
64 username TEXT NOT NULL,
65 redirect_uri TEXT NOT NULL,
66 scopes TEXT NOT NULL,
67 code_challenge TEXT NOT NULL,
68 device_name TEXT NOT NULL,
69 expires_at INTEGER NOT NULL
70 );
71
72 CREATE TABLE IF NOT EXISTS api_entries (
73 root_key TEXT NOT NULL,
74 rel_path TEXT NOT NULL,
75 file_id TEXT NOT NULL,
76 is_dir INTEGER NOT NULL,
77 size INTEGER NOT NULL,
78 mtime_ms INTEGER NOT NULL,
79 version TEXT NOT NULL,
80 PRIMARY KEY (root_key, rel_path)
81 );
82
83 CREATE TABLE IF NOT EXISTS api_changes (
84 seq INTEGER PRIMARY KEY AUTOINCREMENT,
85 root_key TEXT NOT NULL,
86 change TEXT NOT NULL,
87 rel_path TEXT NOT NULL,
88 old_rel_path TEXT,
89 file_id TEXT NOT NULL,
90 is_dir INTEGER NOT NULL,
91 size INTEGER,
92 mtime_ms INTEGER,
93 version TEXT,
94 at INTEGER NOT NULL
95 );
96 CREATE INDEX IF NOT EXISTS idx_api_changes_root ON api_changes(root_key, seq);
97
98 CREATE TABLE IF NOT EXISTS api_scan_state (
99 root_key TEXT PRIMARY KEY,
100 generation TEXT NOT NULL,
101 last_scan_at INTEGER NOT NULL DEFAULT 0,
102 dirty INTEGER NOT NULL DEFAULT 1,
103 min_seq INTEGER NOT NULL DEFAULT 0
104 );
105
106 CREATE TABLE IF NOT EXISTS api_hashes (
107 abs_path TEXT PRIMARY KEY,
108 size INTEGER NOT NULL,
109 mtime_ms INTEGER NOT NULL,
110 sha256 TEXT NOT NULL
111 );
112
113 CREATE TABLE IF NOT EXISTS api_uploads (
114 id TEXT PRIMARY KEY,
115 grant_id TEXT NOT NULL,
116 username TEXT NOT NULL,
117 target TEXT NOT NULL,
118 size INTEGER NOT NULL,
119 received INTEGER NOT NULL DEFAULT 0,
120 sha256 TEXT,
121 mtime_ms INTEGER,
122 if_match TEXT,
123 if_none_match INTEGER NOT NULL DEFAULT 0,
124 overwrite INTEGER NOT NULL DEFAULT 0,
125 created_at INTEGER NOT NULL,
126 expires_at INTEGER NOT NULL
127 );
128 `);
129}
130
131function sha256Hex (value)
132{
133 return crypto.createHash('sha256').update(String(value)).digest('hex');
134}
135
136function randomToken (prefix, bytes = 32)
137{
138 return prefix + crypto.randomBytes(bytes).toString('base64url');
139}
140
141function now ()
142{
143 return Date.now();
144}
145
146function normalizeScopes (raw)
147{
148 const list = Array.isArray(raw) ? raw : String(raw || '').split(/[\s,]+/);
149 const out = [];
150 for (const s of list)
151 {
152 const v = String(s || '').trim();
153 if (!v) continue;
154 if (!SCOPES.includes(v)) return null;
155 if (!out.includes(v)) out.push(v);
156 }
157 // Write implies read: a sync client must see what it changes.
158 if (out.includes('files:write') && !out.includes('files:read')) out.unshift('files:read');
159 return out;
160}
161
162// ---------------------------------------------------------------------------
163// Clients
164// ---------------------------------------------------------------------------
165
166function parseClient (row)
167{
168 if (!row) return null;
169 let uris = [];
170 try { uris = JSON.parse(row.redirect_uris || '[]'); } catch { uris = []; }
171 return {
172 clientId: row.client_id,
173 name: row.name,
174 redirectUris: Array.isArray(uris) ? uris : [],
175 createdBy: row.created_by,
176 createdAt: row.created_at,
177 disabled: !!row.disabled_at,
178 };
179}
180
181function validateRedirectUri (uri)
182{
183 let u;
184 try { u = new URL(String(uri)); } catch { return false; }
185 if (u.hash) return false;
186 if (u.protocol === 'https:') return true;
187 if (u.protocol === 'http:') return u.hostname === '127.0.0.1' || u.hostname === '[::1]' || u.hostname === 'localhost';
188 // Private-use URI scheme for mobile/desktop apps (RFC 8252 7.1), e.g. com.example.app:/cb
189 return /^[a-z][a-z0-9+.-]*\.[a-z0-9+.-]+:$/i.test(u.protocol);
190}
191
192function createClient ({ name, redirectUris, createdBy })
193{
194 const clientId = 'fmc_' + crypto.randomBytes(12).toString('base64url');
195 getDb().prepare('INSERT INTO api_clients (client_id, name, redirect_uris, created_by, created_at) VALUES (?, ?, ?, ?, ?)')
196 .run([clientId, name, JSON.stringify(redirectUris), createdBy, now()]);
197 return getClient(clientId);
198}
199
200function getClient (clientId)
201{
202 return parseClient(getDb().prepare('SELECT * FROM api_clients WHERE client_id = ?').get([String(clientId || '')]));
203}
204
205function listClients ()
206{
207 return getDb().prepare('SELECT * FROM api_clients ORDER BY created_at').all().map(parseClient);
208}
209
210function deleteClient (clientId)
211{
212 const d = getDb();
213 d.prepare('UPDATE api_clients SET disabled_at = ? WHERE client_id = ? AND disabled_at IS NULL').run([now(), clientId]);
214 const grants = d.prepare('SELECT id FROM api_grants WHERE client_id = ? AND revoked_at IS NULL').all([clientId]);
215 for (const g of grants) revokeGrant(g.id);
216}
217
218/**
219 * RFC 8252 7.3: for loopback redirects the port may vary at request time.
220 */
221function redirectUriAllowed (client, uri)
222{
223 if (!client || !uri) return false;
224 if (client.redirectUris.includes(uri)) return true;
225 let req;
226 try { req = new URL(uri); } catch { return false; }
227 if (req.protocol !== 'http:' || !['127.0.0.1', '[::1]', 'localhost'].includes(req.hostname)) return false;
228 return client.redirectUris.some((reg) =>
229 {
230 try
231 {
232 const r = new URL(reg);
233 return r.protocol === 'http:' && r.hostname === req.hostname && r.pathname === req.pathname;
234 } catch { return false; }
235 });
236}
237
238// ---------------------------------------------------------------------------
239// Authorization codes
240// ---------------------------------------------------------------------------
241
242function createAuthCode ({ clientId, username, redirectUri, scopes, codeChallenge, deviceName })
243{
244 const code = randomToken('fmo_');
245 const d = getDb();
246 d.prepare('DELETE FROM api_auth_codes WHERE expires_at < ?').run([now()]);
247 d.prepare(`INSERT INTO api_auth_codes (code_hash, client_id, username, redirect_uri, scopes, code_challenge, device_name, expires_at)
248 VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
249 .run([sha256Hex(code), clientId, username, redirectUri, scopes.join(' '), codeChallenge, deviceName, now() + AUTH_CODE_TTL_MS]);
250 return code;
251}
252
253/** Single use: the row is deleted whether or not the exchange succeeds. */
254function consumeAuthCode (code)
255{
256 const d = getDb();
257 const hash = sha256Hex(code || '');
258 const row = d.prepare('SELECT * FROM api_auth_codes WHERE code_hash = ?').get([hash]);
259 if (!row) return null;
260 d.prepare('DELETE FROM api_auth_codes WHERE code_hash = ?').run([hash]);
261 if (row.expires_at < now()) return null;
262 return row;
263}
264
265function pkceS256 (verifier)
266{
267 return crypto.createHash('sha256').update(String(verifier)).digest('base64url');
268}
269
270// ---------------------------------------------------------------------------
271// Grants and tokens
272// ---------------------------------------------------------------------------
273
274function issueTokensForGrant (grantId)
275{
276 const d = getDb();
277 const accessToken = randomToken('fma_');
278 const refreshToken = randomToken('fmr_');
279 const t = now();
280 d.prepare('DELETE FROM api_access_tokens WHERE expires_at < ?').run([t]);
281 d.prepare('INSERT INTO api_access_tokens (token_hash, grant_id, expires_at) VALUES (?, ?, ?)')
282 .run([sha256Hex(accessToken), grantId, t + ACCESS_TOKEN_TTL_MS]);
283 const g = d.prepare('SELECT refresh_hash FROM api_grants WHERE id = ?').get([grantId]);
284 d.prepare('UPDATE api_grants SET prev_refresh_hash = ?, refresh_hash = ?, refresh_expires_at = ? WHERE id = ?')
285 .run([g ? g.refresh_hash : null, sha256Hex(refreshToken), t + REFRESH_TOKEN_TTL_MS, grantId]);
286 return { accessToken, refreshToken, expiresIn: Math.floor(ACCESS_TOKEN_TTL_MS / 1000) };
287}
288
289function createOAuthGrant ({ username, clientId, name, scopes })
290{
291 const id = 'g_' + crypto.randomBytes(12).toString('base64url');
292 getDb().prepare('INSERT INTO api_grants (id, username, kind, client_id, name, scopes, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)')
293 .run([id, username, 'oauth', clientId, name, scopes.join(' '), now()]);
294 return id;
295}
296
297function createPersonalToken ({ username, name, scopes, expiresAt })
298{
299 const id = 'g_' + crypto.randomBytes(12).toString('base64url');
300 const token = randomToken('fmp_');
301 getDb().prepare('INSERT INTO api_grants (id, username, kind, client_id, name, scopes, created_at, expires_at, secret_hash) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)')
302 .run([id, username, 'personal', null, name, scopes.join(' '), now(), expiresAt || null, sha256Hex(token)]);
303 return { id, token };
304}
305
306function getGrant (id)
307{
308 return getDb().prepare('SELECT * FROM api_grants WHERE id = ?').get([String(id || '')]) || null;
309}
310
311/**
312 * Refresh token rotation with reuse detection: presenting an already rotated
313 * refresh token revokes the whole grant (it was probably stolen).
314 */
315function refreshGrant (clientId, refreshToken)
316{
317 const d = getDb();
318 const hash = sha256Hex(refreshToken || '');
319 const g = d.prepare('SELECT * FROM api_grants WHERE refresh_hash = ?').get([hash]);
320 if (!g)
321 {
322 const reused = d.prepare('SELECT id FROM api_grants WHERE prev_refresh_hash = ?').get([hash]);
323 if (reused) revokeGrant(reused.id);
324 return { error: 'invalid_grant' };
325 }
326 if (g.revoked_at || g.client_id !== clientId || !g.refresh_expires_at || g.refresh_expires_at < now())
327 {
328 return { error: 'invalid_grant' };
329 }
330 const client = getClient(g.client_id);
331 if (!client || client.disabled) return { error: 'invalid_grant' };
332 if (!userExists(g.username)) return { error: 'invalid_grant' };
333 return { grant: g, tokens: issueTokensForGrant(g.id) };
334}
335
336function revokeGrant (id)
337{
338 const d = getDb();
339 d.prepare('UPDATE api_grants SET revoked_at = ?, refresh_hash = NULL, prev_refresh_hash = NULL, secret_hash = NULL WHERE id = ? AND revoked_at IS NULL')
340 .run([now(), id]);
341 d.prepare('DELETE FROM api_access_tokens WHERE grant_id = ?').run([id]);
342 d.prepare('DELETE FROM api_uploads WHERE grant_id = ?').run([id]);
343}
344
345function revokeAllForUser (username)
346{
347 const rows = getDb().prepare('SELECT id FROM api_grants WHERE username = ? AND revoked_at IS NULL').all([username]);
348 for (const r of rows) revokeGrant(r.id);
349}
350
351/** Revoke by presenting either the access or the refresh token (RFC 7009). */
352function revokeByToken (token)
353{
354 const d = getDb();
355 const hash = sha256Hex(token || '');
356 const at = d.prepare('SELECT grant_id FROM api_access_tokens WHERE token_hash = ?').get([hash]);
357 if (at) { revokeGrant(at.grant_id); return true; }
358 const g = d.prepare('SELECT id FROM api_grants WHERE refresh_hash = ? OR secret_hash = ?').get([hash, hash]);
359 if (g) { revokeGrant(g.id); return true; }
360 return false;
361}
362
363function userExists (username)
364{
365 return !!getDb().prepare('SELECT 1 AS ok FROM users WHERE username = ?').get([username]);
366}
367
368/**
369 * Resolve a bearer token to { grant, scopes }. Returns null when the token is
370 * unknown, expired or revoked.
371 */
372function resolveBearer (token)
373{
374 const t = String(token || '');
375 if (!t) return null;
376 const d = getDb();
377 const hash = sha256Hex(t);
378 let grant = null;
379 if (t.startsWith('fma_'))
380 {
381 const row = d.prepare('SELECT grant_id, expires_at FROM api_access_tokens WHERE token_hash = ?').get([hash]);
382 if (!row || row.expires_at < now()) return null;
383 grant = getGrant(row.grant_id);
384 } else if (t.startsWith('fmp_'))
385 {
386 grant = d.prepare('SELECT * FROM api_grants WHERE secret_hash = ?').get([hash]) || null;
387 if (grant && grant.expires_at && grant.expires_at < now()) return null;
388 }
389 if (!grant || grant.revoked_at) return null;
390 if (grant.kind === 'oauth')
391 {
392 const client = getClient(grant.client_id);
393 if (!client || client.disabled) return null;
394 }
395 return { grant, scopes: String(grant.scopes || '').split(' ').filter(Boolean) };
396}
397
398function touchGrant (id, ip)
399{
400 const g = getGrant(id);
401 if (!g) return;
402 const t = now();
403 if (!g.last_used_at || t - g.last_used_at > 60 * 1000 || g.last_used_ip !== ip)
404 {
405 getDb().prepare('UPDATE api_grants SET last_used_at = ?, last_used_ip = ? WHERE id = ?').run([t, ip, id]);
406 }
407}
408
409function listGrantsForUser (username)
410{
411 return getDb().prepare(`SELECT g.*, c.name AS client_name FROM api_grants g LEFT JOIN api_clients c ON c.client_id = g.client_id
412 WHERE g.username = ? AND g.revoked_at IS NULL ORDER BY g.created_at DESC`)
413 .all([username])
414 .map((g) => ({
415 id: g.id,
416 kind: g.kind,
417 name: g.name,
418 clientId: g.client_id,
419 clientName: g.client_name || null,
420 scopes: String(g.scopes || '').split(' ').filter(Boolean),
421 createdAt: g.created_at,
422 lastUsedAt: g.last_used_at,
423 lastUsedIp: g.last_used_ip,
424 expiresAt: g.expires_at || (g.kind === 'oauth' ? g.refresh_expires_at : null),
425 }));
426}
427
428module.exports = {
429 SCOPES,
430 SCOPE_DESCRIPTIONS,
431 ACCESS_TOKEN_TTL_MS,
432 REFRESH_TOKEN_TTL_MS,
433 initApiSchema,
434 sha256Hex,
435 normalizeScopes,
436 validateRedirectUri,
437 createClient,
438 getClient,
439 listClients,
440 deleteClient,
441 redirectUriAllowed,
442 createAuthCode,
443 consumeAuthCode,
444 pkceS256,
445 createOAuthGrant,
446 createPersonalToken,
447 issueTokensForGrant,
448 refreshGrant,
449 revokeGrant,
450 revokeAllForUser,
451 revokeByToken,
452 resolveBearer,
453 touchGrant,
454 getGrant,
455 listGrantsForUser,
456 userExists,
457};
server/api/sync-index.js added +306 −0
@@ -0,0 +1,306 @@
1 'use strict';
2
3 // Change journal for the sync API. Files can change through the web UI, the
4 // API or directly on disk, so instead of hooking every writer we keep a
5 // snapshot per root (api_entries) and diff it against the filesystem. The
6 // diff is written to api_changes, which feeds the cursor-based delta API.
7 // Moves/renames are detected by (device, inode) identity.
8
9 const fs = require('fs');
10 const path = require('path');
11 const crypto = require('crypto');
12 const { getDb } = require('../db');
13
14 const DEFAULT_SCAN_INTERVAL_MS = 15 * 1000;
15 const DEFAULT_MAX_ENTRIES = 500000;
16 const CHANGE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
17 const TEMP_PREFIX = '.fmapi-';
18
19 const locks = new Map();
20
21 function shortHash (value, len = 22)
22 {
23 return crypto.createHash('sha256').update(String(value)).digest('base64url').slice(0, len);
24 }
25
26 function fileIdFor (stat)
27 {
28 return shortHash(`${stat.dev}:${stat.ino}`);
29 }
30
31 function versionFor (stat)
32 {
33 const mtime = Math.floor(Number(stat.mtimeMs) || 0);
34 return shortHash(`${stat.ino}:${stat.isDirectory() ? 'd' : stat.size}:${mtime}:${Math.floor(Number(stat.ctimeMs) || 0)}`, 16);
35 }
36
37 function isIgnoredName (name)
38 {
39 return String(name).startsWith(TEMP_PREFIX);
40 }
41
42 function entryFromStat (relPath, stat)
43 {
44 return {
45 rel_path: relPath,
46 file_id: fileIdFor(stat),
47 is_dir: stat.isDirectory() ? 1 : 0,
48 size: stat.isDirectory() ? 0 : stat.size,
49 mtime_ms: Math.floor(Number(stat.mtimeMs) || 0),
50 version: versionFor(stat),
51 };
52 }
53
54 async function walk (rootAbs, maxEntries)
55 {
56 const out = new Map();
57 const stack = [''];
58 while (stack.length)
59 {
60 const rel = stack.pop();
61 let dirents;
62 try
63 {
64 dirents = await fs.promises.readdir(path.join(rootAbs, rel), { withFileTypes: true });
65 } catch
66 {
67 continue;
68 }
69 for (const d of dirents)
70 {
71 if (isIgnoredName(d.name)) continue;
72 if (d.isSymbolicLink()) continue;
73 if (!d.isFile() && !d.isDirectory()) continue;
74 const childRel = rel ? `${rel}/${d.name}` : d.name;
75 let stat;
76 try { stat = await fs.promises.lstat(path.join(rootAbs, childRel)); } catch { continue; }
77 out.set(childRel, entryFromStat(childRel, stat));
78 if (out.size > maxEntries)
79 {
80 const err = new Error(`Root has more than ${maxEntries} entries; raise api.maxSyncEntries.`);
81 err.code = 'too_many_entries';
82 throw err;
83 }
84 if (stat.isDirectory()) stack.push(childRel);
85 }
86 }
87 return out;
88 }
89
90 function parentOf (rel)
91 {
92 const i = rel.lastIndexOf('/');
93 return i < 0 ? '' : rel.slice(0, i);
94 }
95
96 function depth (rel)
97 {
98 return rel.split('/').length;
99 }
100
101 function getState (rootKey)
102 {
103 return getDb().prepare('SELECT * FROM api_scan_state WHERE root_key = ?').get([rootKey]) || null;
104 }
105
106 function currentSeq ()
107 {
108 const row = getDb().prepare("SELECT seq FROM sqlite_sequence WHERE name = 'api_changes'").get();
109 return row ? Number(row.seq) : 0;
110 }
111
112 function diff (oldMap, newMap)
113 {
114 const removed = [];
115 const added = [];
116 const modified = [];
117 for (const [rel, o] of oldMap)
118 {
119 const n = newMap.get(rel);
120 if (!n || n.file_id !== o.file_id || n.is_dir !== o.is_dir) removed.push(o);
121 else if (n.version !== o.version && !n.is_dir) modified.push(n);
122 }
123 for (const [rel, n] of newMap)
124 {
125 const o = oldMap.get(rel);
126 if (!o || o.file_id !== n.file_id || o.is_dir !== n.is_dir) added.push(n);
127 }
128
129 const removedById = new Map(removed.map((e) => [e.file_id, e]));
130 const moves = [];
131 const created = [];
132 for (const n of added)
133 {
134 const o = removedById.get(n.file_id);
135 if (o && o.is_dir === n.is_dir)
136 {
137 removedById.delete(n.file_id);
138 moves.push({ from: o, to: n });
139 } else
140 {
141 created.push(n);
142 }
143 }
144 const deleted = [...removedById.values()];
145
146 // Collapse implied children: a moved/deleted folder covers its contents.
147 const movedFrom = new Map(moves.map((m) => [m.from.rel_path, m.to.rel_path]));
148 const effMoves = moves.filter((m) =>
149 {
150 const p = parentOf(m.from.rel_path);
151 if (!p || !movedFrom.has(p)) return true;
152 const impliedTo = `${movedFrom.get(p)}/${path.posix.basename(m.from.rel_path)}`;
153 if (impliedTo !== m.to.rel_path) return true;
154 // Implied by parent move, but report a content change if any.
155 if (!m.to.is_dir && m.to.version !== m.from.version) modified.push(m.to);
156 return false;
157 });
158 const deletedSet = new Set(deleted.filter((e) => e.is_dir).map((e) => e.rel_path));
159 const effDeleted = deleted.filter((e) =>
160 {
161 let p = parentOf(e.rel_path);
162 while (p)
163 {
164 if (deletedSet.has(p)) return false;
165 p = parentOf(p);
166 }
167 return true;
168 });
169
170 effDeleted.sort((a, b) => depth(b.rel_path) - depth(a.rel_path));
171 effMoves.sort((a, b) => depth(a.to.rel_path) - depth(b.to.rel_path));
172 created.sort((a, b) => depth(a.rel_path) - depth(b.rel_path) || a.rel_path.localeCompare(b.rel_path));
173
174 // Order: moves first (so clients can rename locally), then deletes, creates, modifies.
175 const changes = [];
176 for (const m of effMoves) changes.push({ change: 'moved', ...m.to, old_rel_path: m.from.rel_path });
177 for (const e of effDeleted) changes.push({ change: 'deleted', ...e, old_rel_path: null });
178 for (const e of created) changes.push({ change: 'created', ...e, old_rel_path: null });
179 for (const e of modified) changes.push({ change: 'modified', ...e, old_rel_path: null });
180 return { changes, removed, added, modified };
181 }
182
183 async function scanRoot (rootKey, rootAbs, opts = {})
184 {
185 const maxEntries = opts.maxEntries || DEFAULT_MAX_ENTRIES;
186 const newMap = await walk(rootAbs, maxEntries);
187 const d = getDb();
188 const state = getState(rootKey);
189 const t = Date.now();
190
191 const oldMap = new Map();
192 for (const row of d.prepare('SELECT rel_path, file_id, is_dir, size, mtime_ms, version FROM api_entries WHERE root_key = ?').all([rootKey]))
193 {
194 oldMap.set(row.rel_path, row);
195 }
196
197 const { changes } = state ? diff(oldMap, newMap) : { changes: [] };
198
199 d.exec('BEGIN');
200 try
201 {
202 const del = d.prepare('DELETE FROM api_entries WHERE root_key = ? AND rel_path = ?');
203 const up = d.prepare(`INSERT INTO api_entries (root_key, rel_path, file_id, is_dir, size, mtime_ms, version) VALUES (?, ?, ?, ?, ?, ?, ?)
204 ON CONFLICT(root_key, rel_path) DO UPDATE SET file_id = excluded.file_id, is_dir = excluded.is_dir,
205 size = excluded.size, mtime_ms = excluded.mtime_ms, version = excluded.version`);
206 for (const rel of oldMap.keys())
207 {
208 if (!newMap.has(rel)) del.run([rootKey, rel]);
209 }
210 for (const [rel, n] of newMap)
211 {
212 const o = oldMap.get(rel);
213 if (!o || o.version !== n.version || o.file_id !== n.file_id || o.is_dir !== n.is_dir)
214 {
215 up.run([rootKey, rel, n.file_id, n.is_dir, n.size, n.mtime_ms, n.version]);
216 }
217 }
218 del.finalize();
219 up.finalize();
220 if (changes.length)
221 {
222 const ins = d.prepare(`INSERT INTO api_changes (root_key, change, rel_path, old_rel_path, file_id, is_dir, size, mtime_ms, version, at)
223 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
224 for (const c of changes)
225 {
226 ins.run([rootKey, c.change, c.rel_path, c.old_rel_path, c.file_id, c.is_dir,
227 c.change === 'deleted' ? null : c.size, c.change === 'deleted' ? null : c.mtime_ms, c.change === 'deleted' ? null : c.version, t]);
228 }
229 ins.finalize();
230 }
231 if (!state)
232 {
233 d.prepare('INSERT INTO api_scan_state (root_key, generation, last_scan_at, dirty, min_seq) VALUES (?, ?, ?, 0, ?)')
234 .run([rootKey, crypto.randomBytes(6).toString('base64url'), t, currentSeq()]);
235 } else
236 {
237 d.prepare('UPDATE api_scan_state SET last_scan_at = ?, dirty = 0 WHERE root_key = ?').run([t, rootKey]);
238 }
239 pruneChanges(rootKey, t);
240 d.exec('COMMIT');
241 } catch (err)
242 {
243 try { d.exec('ROLLBACK'); } catch { /* ignore */ }
244 throw err;
245 }
246 return { changes: changes.length };
247 }
248
249 function pruneChanges (rootKey, t)
250 {
251 const d = getDb();
252 const cutoff = t - CHANGE_RETENTION_MS;
253 const row = d.prepare('SELECT MAX(seq) AS s FROM api_changes WHERE root_key = ? AND at < ?').get([rootKey, cutoff]);
254 if (row && row.s)
255 {
256 d.prepare('DELETE FROM api_changes WHERE root_key = ? AND seq <= ?').run([rootKey, row.s]);
257 d.prepare('UPDATE api_scan_state SET min_seq = MAX(min_seq, ?) WHERE root_key = ?').run([row.s, rootKey]);
258 }
259 }
260
261 /** Scan when dirty, never scanned, or older than the interval. Serialised per root. */
262 async function ensureFresh (rootKey, rootAbs, opts = {})
263 {
264 const interval = opts.intervalMs != null ? opts.intervalMs : DEFAULT_SCAN_INTERVAL_MS;
265 const running = locks.get(rootKey);
266 if (running) await running.catch(() => {});
267 const state = getState(rootKey);
268 if (state && !state.dirty && !opts.force && Date.now() - state.last_scan_at < interval) return state;
269 const p = scanRoot(rootKey, rootAbs, opts).finally(() => locks.delete(rootKey));
270 locks.set(rootKey, p);
271 await p;
272 return getState(rootKey);
273 }
274
275 function markDirty (rootKey)
276 {
277 getDb().prepare('UPDATE api_scan_state SET dirty = 1 WHERE root_key = ?').run([rootKey]);
278 }
279
280 function listChanges (rootKey, afterSeq, limit)
281 {
282 return getDb().prepare('SELECT * FROM api_changes WHERE root_key = ? AND seq > ? ORDER BY seq LIMIT ?')
283 .all([rootKey, afterSeq, limit]);
284 }
285
286 function listEntries (rootKey, offset, limit)
287 {
288 return getDb().prepare('SELECT * FROM api_entries WHERE root_key = ? ORDER BY rel_path LIMIT ? OFFSET ?')
289 .all([rootKey, limit, offset]);
290 }
291
292 module.exports = {
293 TEMP_PREFIX,
294 fileIdFor,
295 versionFor,
296 isIgnoredName,
297 entryFromStat,
298 ensureFresh,
299 scanRoot,
300 markDirty,
301 listChanges,
302 listEntries,
303 currentSeq,
304 getState,
305 diff,
306 };
@@ -0,0 +1,306 @@
1'use strict';
2
3// Change journal for the sync API. Files can change through the web UI, the
4// API or directly on disk, so instead of hooking every writer we keep a
5// snapshot per root (api_entries) and diff it against the filesystem. The
6// diff is written to api_changes, which feeds the cursor-based delta API.
7// Moves/renames are detected by (device, inode) identity.
8
9const fs = require('fs');
10const path = require('path');
11const crypto = require('crypto');
12const { getDb } = require('../db');
13
14const DEFAULT_SCAN_INTERVAL_MS = 15 * 1000;
15const DEFAULT_MAX_ENTRIES = 500000;
16const CHANGE_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
17const TEMP_PREFIX = '.fmapi-';
18
19const locks = new Map();
20
21function shortHash (value, len = 22)
22{
23 return crypto.createHash('sha256').update(String(value)).digest('base64url').slice(0, len);
24}
25
26function fileIdFor (stat)
27{
28 return shortHash(`${stat.dev}:${stat.ino}`);
29}
30
31function versionFor (stat)
32{
33 const mtime = Math.floor(Number(stat.mtimeMs) || 0);
34 return shortHash(`${stat.ino}:${stat.isDirectory() ? 'd' : stat.size}:${mtime}:${Math.floor(Number(stat.ctimeMs) || 0)}`, 16);
35}
36
37function isIgnoredName (name)
38{
39 return String(name).startsWith(TEMP_PREFIX);
40}
41
42function entryFromStat (relPath, stat)
43{
44 return {
45 rel_path: relPath,
46 file_id: fileIdFor(stat),
47 is_dir: stat.isDirectory() ? 1 : 0,
48 size: stat.isDirectory() ? 0 : stat.size,
49 mtime_ms: Math.floor(Number(stat.mtimeMs) || 0),
50 version: versionFor(stat),
51 };
52}
53
54async function walk (rootAbs, maxEntries)
55{
56 const out = new Map();
57 const stack = [''];
58 while (stack.length)
59 {
60 const rel = stack.pop();
61 let dirents;
62 try
63 {
64 dirents = await fs.promises.readdir(path.join(rootAbs, rel), { withFileTypes: true });
65 } catch
66 {
67 continue;
68 }
69 for (const d of dirents)
70 {
71 if (isIgnoredName(d.name)) continue;
72 if (d.isSymbolicLink()) continue;
73 if (!d.isFile() && !d.isDirectory()) continue;
74 const childRel = rel ? `${rel}/${d.name}` : d.name;
75 let stat;
76 try { stat = await fs.promises.lstat(path.join(rootAbs, childRel)); } catch { continue; }
77 out.set(childRel, entryFromStat(childRel, stat));
78 if (out.size > maxEntries)
79 {
80 const err = new Error(`Root has more than ${maxEntries} entries; raise api.maxSyncEntries.`);
81 err.code = 'too_many_entries';
82 throw err;
83 }
84 if (stat.isDirectory()) stack.push(childRel);
85 }
86 }
87 return out;
88}
89
90function parentOf (rel)
91{
92 const i = rel.lastIndexOf('/');
93 return i < 0 ? '' : rel.slice(0, i);
94}
95
96function depth (rel)
97{
98 return rel.split('/').length;
99}
100
101function getState (rootKey)
102{
103 return getDb().prepare('SELECT * FROM api_scan_state WHERE root_key = ?').get([rootKey]) || null;
104}
105
106function currentSeq ()
107{
108 const row = getDb().prepare("SELECT seq FROM sqlite_sequence WHERE name = 'api_changes'").get();
109 return row ? Number(row.seq) : 0;
110}
111
112function diff (oldMap, newMap)
113{
114 const removed = [];
115 const added = [];
116 const modified = [];
117 for (const [rel, o] of oldMap)
118 {
119 const n = newMap.get(rel);
120 if (!n || n.file_id !== o.file_id || n.is_dir !== o.is_dir) removed.push(o);
121 else if (n.version !== o.version && !n.is_dir) modified.push(n);
122 }
123 for (const [rel, n] of newMap)
124 {
125 const o = oldMap.get(rel);
126 if (!o || o.file_id !== n.file_id || o.is_dir !== n.is_dir) added.push(n);
127 }
128
129 const removedById = new Map(removed.map((e) => [e.file_id, e]));
130 const moves = [];
131 const created = [];
132 for (const n of added)
133 {
134 const o = removedById.get(n.file_id);
135 if (o && o.is_dir === n.is_dir)
136 {
137 removedById.delete(n.file_id);
138 moves.push({ from: o, to: n });
139 } else
140 {
141 created.push(n);
142 }
143 }
144 const deleted = [...removedById.values()];
145
146 // Collapse implied children: a moved/deleted folder covers its contents.
147 const movedFrom = new Map(moves.map((m) => [m.from.rel_path, m.to.rel_path]));
148 const effMoves = moves.filter((m) =>
149 {
150 const p = parentOf(m.from.rel_path);
151 if (!p || !movedFrom.has(p)) return true;
152 const impliedTo = `${movedFrom.get(p)}/${path.posix.basename(m.from.rel_path)}`;
153 if (impliedTo !== m.to.rel_path) return true;
154 // Implied by parent move, but report a content change if any.
155 if (!m.to.is_dir && m.to.version !== m.from.version) modified.push(m.to);
156 return false;
157 });
158 const deletedSet = new Set(deleted.filter((e) => e.is_dir).map((e) => e.rel_path));
159 const effDeleted = deleted.filter((e) =>
160 {
161 let p = parentOf(e.rel_path);
162 while (p)
163 {
164 if (deletedSet.has(p)) return false;
165 p = parentOf(p);
166 }
167 return true;
168 });
169
170 effDeleted.sort((a, b) => depth(b.rel_path) - depth(a.rel_path));
171 effMoves.sort((a, b) => depth(a.to.rel_path) - depth(b.to.rel_path));
172 created.sort((a, b) => depth(a.rel_path) - depth(b.rel_path) || a.rel_path.localeCompare(b.rel_path));
173
174 // Order: moves first (so clients can rename locally), then deletes, creates, modifies.
175 const changes = [];
176 for (const m of effMoves) changes.push({ change: 'moved', ...m.to, old_rel_path: m.from.rel_path });
177 for (const e of effDeleted) changes.push({ change: 'deleted', ...e, old_rel_path: null });
178 for (const e of created) changes.push({ change: 'created', ...e, old_rel_path: null });
179 for (const e of modified) changes.push({ change: 'modified', ...e, old_rel_path: null });
180 return { changes, removed, added, modified };
181}
182
183async function scanRoot (rootKey, rootAbs, opts = {})
184{
185 const maxEntries = opts.maxEntries || DEFAULT_MAX_ENTRIES;
186 const newMap = await walk(rootAbs, maxEntries);
187 const d = getDb();
188 const state = getState(rootKey);
189 const t = Date.now();
190
191 const oldMap = new Map();
192 for (const row of d.prepare('SELECT rel_path, file_id, is_dir, size, mtime_ms, version FROM api_entries WHERE root_key = ?').all([rootKey]))
193 {
194 oldMap.set(row.rel_path, row);
195 }
196
197 const { changes } = state ? diff(oldMap, newMap) : { changes: [] };
198
199 d.exec('BEGIN');
200 try
201 {
202 const del = d.prepare('DELETE FROM api_entries WHERE root_key = ? AND rel_path = ?');
203 const up = d.prepare(`INSERT INTO api_entries (root_key, rel_path, file_id, is_dir, size, mtime_ms, version) VALUES (?, ?, ?, ?, ?, ?, ?)
204 ON CONFLICT(root_key, rel_path) DO UPDATE SET file_id = excluded.file_id, is_dir = excluded.is_dir,
205 size = excluded.size, mtime_ms = excluded.mtime_ms, version = excluded.version`);
206 for (const rel of oldMap.keys())
207 {
208 if (!newMap.has(rel)) del.run([rootKey, rel]);
209 }
210 for (const [rel, n] of newMap)
211 {
212 const o = oldMap.get(rel);
213 if (!o || o.version !== n.version || o.file_id !== n.file_id || o.is_dir !== n.is_dir)
214 {
215 up.run([rootKey, rel, n.file_id, n.is_dir, n.size, n.mtime_ms, n.version]);
216 }
217 }
218 del.finalize();
219 up.finalize();
220 if (changes.length)
221 {
222 const ins = d.prepare(`INSERT INTO api_changes (root_key, change, rel_path, old_rel_path, file_id, is_dir, size, mtime_ms, version, at)
223 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
224 for (const c of changes)
225 {
226 ins.run([rootKey, c.change, c.rel_path, c.old_rel_path, c.file_id, c.is_dir,
227 c.change === 'deleted' ? null : c.size, c.change === 'deleted' ? null : c.mtime_ms, c.change === 'deleted' ? null : c.version, t]);
228 }
229 ins.finalize();
230 }
231 if (!state)
232 {
233 d.prepare('INSERT INTO api_scan_state (root_key, generation, last_scan_at, dirty, min_seq) VALUES (?, ?, ?, 0, ?)')
234 .run([rootKey, crypto.randomBytes(6).toString('base64url'), t, currentSeq()]);
235 } else
236 {
237 d.prepare('UPDATE api_scan_state SET last_scan_at = ?, dirty = 0 WHERE root_key = ?').run([t, rootKey]);
238 }
239 pruneChanges(rootKey, t);
240 d.exec('COMMIT');
241 } catch (err)
242 {
243 try { d.exec('ROLLBACK'); } catch { /* ignore */ }
244 throw err;
245 }
246 return { changes: changes.length };
247}
248
249function pruneChanges (rootKey, t)
250{
251 const d = getDb();
252 const cutoff = t - CHANGE_RETENTION_MS;
253 const row = d.prepare('SELECT MAX(seq) AS s FROM api_changes WHERE root_key = ? AND at < ?').get([rootKey, cutoff]);
254 if (row && row.s)
255 {
256 d.prepare('DELETE FROM api_changes WHERE root_key = ? AND seq <= ?').run([rootKey, row.s]);
257 d.prepare('UPDATE api_scan_state SET min_seq = MAX(min_seq, ?) WHERE root_key = ?').run([row.s, rootKey]);
258 }
259}
260
261/** Scan when dirty, never scanned, or older than the interval. Serialised per root. */
262async function ensureFresh (rootKey, rootAbs, opts = {})
263{
264 const interval = opts.intervalMs != null ? opts.intervalMs : DEFAULT_SCAN_INTERVAL_MS;
265 const running = locks.get(rootKey);
266 if (running) await running.catch(() => {});
267 const state = getState(rootKey);
268 if (state && !state.dirty && !opts.force && Date.now() - state.last_scan_at < interval) return state;
269 const p = scanRoot(rootKey, rootAbs, opts).finally(() => locks.delete(rootKey));
270 locks.set(rootKey, p);
271 await p;
272 return getState(rootKey);
273}
274
275function markDirty (rootKey)
276{
277 getDb().prepare('UPDATE api_scan_state SET dirty = 1 WHERE root_key = ?').run([rootKey]);
278}
279
280function listChanges (rootKey, afterSeq, limit)
281{
282 return getDb().prepare('SELECT * FROM api_changes WHERE root_key = ? AND seq > ? ORDER BY seq LIMIT ?')
283 .all([rootKey, afterSeq, limit]);
284}
285
286function listEntries (rootKey, offset, limit)
287{
288 return getDb().prepare('SELECT * FROM api_entries WHERE root_key = ? ORDER BY rel_path LIMIT ? OFFSET ?')
289 .all([rootKey, limit, offset]);
290}
291
292module.exports = {
293 TEMP_PREFIX,
294 fileIdFor,
295 versionFor,
296 isIgnoredName,
297 entryFromStat,
298 ensureFresh,
299 scanRoot,
300 markDirty,
301 listChanges,
302 listEntries,
303 currentSeq,
304 getState,
305 diff,
306};
server/api/v1.js added +842 −0
@@ -0,0 +1,842 @@
1 'use strict';
2
3 // Public, versioned file API for sync clients (phones, desktops, services).
4 // Auth: Bearer access tokens from /oauth/token or personal access tokens.
5 // Every request is checked with the same permission helpers as the web UI,
6 // so a token can never see or change more than its user.
7
8 const express = require('express');
9 const fs = require('fs');
10 const path = require('path');
11 const crypto = require('crypto');
12 const { pipeline } = require('stream/promises');
13 const { Transform } = require('stream');
14
15 const store = require('./store');
16 const syncIndex = require('./sync-index');
17 const { getDb } = require('../db');
18 const { getClientIp } = require('../auth');
19 const { logError } = require('../logger');
20 const filesRouter = require('../routes/files');
21 const { deleteIndexUnder, rewriteIndexPaths, reindexDirectoryTree } = require('../search-index');
22 const { enqueueFileHash } = require('../file-hash-queue');
23
24 const helpers = filesRouter.helpers;
25 const router = express.Router();
26 const json = express.json({ limit: '256kb' });
27
28 const USER_ROOT_ID = '~';
29 const GB = 1024 ** 3;
30 const MB = 1024 ** 2;
31 const DEFAULTS = {
32 maxUploadBytes: 10 * GB,
33 maxChunkBytes: 64 * MB,
34 maxOpenUploadsPerUser: 20,
35 uploadTtlHours: 24,
36 maxHashBytes: 4 * GB,
37 scanIntervalSeconds: 15,
38 maxSyncEntries: 500000,
39 };
40 const API_UPLOAD_DIR_DEFAULT = path.join(__dirname, '../../api-uploads');
41
42 // ---------------------------------------------------------------------------
43 // Helpers
44 // ---------------------------------------------------------------------------
45
46 class ApiError extends Error
47 {
48 constructor (status, code, message, extra)
49 {
50 super(message);
51 this.status = status;
52 this.code = code;
53 this.extra = extra;
54 }
55 }
56
57 function apiConfig (config)
58 {
59 const raw = config && typeof config.api === 'object' && config.api ? config.api : {};
60 const out = { ...DEFAULTS };
61 for (const k of Object.keys(DEFAULTS))
62 {
63 const v = Number(raw[k]);
64 if (Number.isFinite(v) && v > 0) out[k] = v;
65 }
66 out.uploadDir = typeof raw.uploadDir === 'string' && raw.uploadDir.trim() ? raw.uploadDir.trim() : API_UPLOAD_DIR_DEFAULT;
67 return out;
68 }
69
70 function sendError (res, err)
71 {
72 if (!(err instanceof ApiError))
73 {
74 logError('API v1 request failed', err);
75 err = new ApiError(500, 'internal_error', 'Internal server error.');
76 }
77 if (res.headersSent) { res.destroy(); return; }
78 res.status(err.status).json({ error: err.code, message: err.message, ...(err.extra || {}) });
79 }
80
81 const wrap = (fn) => (req, res) => Promise.resolve(fn(req, res)).catch((err) => sendError(res, err));
82
83 function parseEtag (value)
84 {
85 const v = String(value || '').trim();
86 if (!v) return null;
87 return v.replace(/^W\//, '').replace(/^"|"$/g, '');
88 }
89
90 function loadApiUser (username)
91 {
92 const row = getDb().prepare('SELECT id, username, is_admin, permissions FROM users WHERE username = ?').get([username]);
93 if (!row) return null;
94 let permissions = {};
95 try { permissions = JSON.parse(row.permissions || '{}'); } catch { permissions = {}; }
96 return { id: row.id, username: row.username, isAdmin: row.is_admin === 1, permissions };
97 }
98
99 function authenticate (req, res, next)
100 {
101 const header = req.get('authorization') || '';
102 const token = header.startsWith('Bearer ') ? header.slice(7).trim() : '';
103 const resolved = store.resolveBearer(token);
104 const user = resolved ? loadApiUser(resolved.grant.username) : null;
105 if (!resolved || !user)
106 {
107 res.set('WWW-Authenticate', 'Bearer error="invalid_token"');
108 return res.status(401).json({ error: 'invalid_token', message: 'Missing, invalid, expired or revoked access token.' });
109 }
110 store.touchGrant(resolved.grant.id, getClientIp(req));
111 req.user = user;
112 req.apiGrant = resolved.grant;
113 req.apiScopes = resolved.scopes;
114 next();
115 }
116
117 function requireScope (scope)
118 {
119 return (req, res, next) =>
120 {
121 if (!req.apiScopes.includes(scope))
122 {
123 res.set('WWW-Authenticate', `Bearer error="insufficient_scope", scope="${scope}"`);
124 return res.status(403).json({ error: 'insufficient_scope', message: `This token lacks the ${scope} scope.` });
125 }
126 next();
127 };
128 }
129
130 /** Roots visible to the user, keyed by a stable id used in virtual paths. */
131 function rootsForUser (user)
132 {
133 const { config, roots } = helpers.loadConfigAndRoots();
134 const aliases = config.rootAliases && typeof config.rootAliases === 'object' ? config.rootAliases : {};
135 const list = [];
136 const userFolder = helpers.getUserFolderPath(config, user.username);
137 if (userFolder)
138 {
139 try { fs.mkdirSync(userFolder, { recursive: true }); } catch { /* non-fatal */ }
140 list.push({ id: USER_ROOT_ID, name: 'My Folder', abs: path.resolve(userFolder), writable: true, isUserFolder: true });
141 }
142 const seen = new Set(list.map((r) => r.id));
143 for (const r of roots)
144 {
145 const label = path.basename(r);
146 if (!helpers.canRead(user, label) || seen.has(label)) continue;
147 const info = helpers.resolveRootForUser(r, roots, user, config);
148 seen.add(label);
149 list.push({
150 id: label,
151 name: String(aliases[path.resolve(r)] || '').trim() || label,
152 abs: path.resolve(r),
153 writable: !!(info && helpers.canWriteInfo(user, info)),
154 isUserFolder: false,
155 });
156 }
157 return { config, roots, list };
158 }
159
160 function validSegment (s)
161 {
162 return s && s !== '.' && s !== '..' && !s.includes('\0') && !s.includes('\\') && Buffer.byteLength(s) <= 255;
163 }
164
165 /**
166 * Resolve a virtual path ("/<root>/a/b") for the user. Throws ApiError.
167 * Returns { root, rel, abs, vpath, config, info }.
168 */
169 function resolvePath (user, vpath, { write = false, ctx } = {})
170 {
171 const raw = String(vpath == null ? '' : vpath);
172 if (!raw.startsWith('/')) throw new ApiError(400, 'invalid_path', 'Paths must start with /<root-id>/.');
173 if (raw.length > 4096) throw new ApiError(400, 'invalid_path', 'Path too long.');
174 const parts = raw.split('/').slice(1).filter((p, i, arr) => !(p === '' && i === arr.length - 1));
175 if (!parts.length || parts.some((p) => !validSegment(p))) throw new ApiError(400, 'invalid_path', 'Invalid path segment.');
176 const c = ctx || rootsForUser(user);
177 const root = c.list.find((r) => r.id === parts[0]);
178 if (!root) throw new ApiError(404, 'not_found', 'No such root.');
179 const rel = parts.slice(1).join('/');
180 const abs = rel ? path.join(root.abs, ...parts.slice(1)) : root.abs;
181
182 // Same checks as the web UI, so the API can never exceed the user's rights.
183 const info = helpers.resolveRootForUser(abs, c.roots, user, c.config);
184 if (!info || !helpers.canReadInfo(user, info)) throw new ApiError(404, 'not_found', 'Not found.');
185 if (write && !helpers.canWriteInfo(user, info)) throw new ApiError(403, 'forbidden', 'You do not have write access here.');
186
187 // Refuse paths that escape the root through symlinks.
188 let probe = abs;
189 while (probe !== root.abs && !fs.existsSync(probe)) probe = path.dirname(probe);
190 try
191 {
192 const realRoot = fs.realpathSync(root.abs);
193 const realProbe = fs.realpathSync(probe);
194 if (realProbe !== realRoot && !realProbe.startsWith(realRoot + path.sep)) throw new ApiError(404, 'not_found', 'Not found.');
195 } catch (err)
196 {
197 if (err instanceof ApiError) throw err;
198 }
199
200 return { root, rel, abs, vpath: '/' + [root.id, ...parts.slice(1)].join('/'), config: c.config, info, ctx: c };
201 }
202
203 function lstatOrNull (abs)
204 {
205 try { return fs.lstatSync(abs); } catch { return null; }
206 }
207
208 function knownSha256 (abs, stat)
209 {
210 const row = getDb().prepare('SELECT size, mtime_ms, sha256 FROM api_hashes WHERE abs_path = ?').get([abs]);
211 if (row && Number(row.size) === stat.size && Number(row.mtime_ms) === Math.floor(stat.mtimeMs)) return row.sha256;
212 return null;
213 }
214
215 function rememberSha256 (abs, stat, sha)
216 {
217 getDb().prepare(`INSERT INTO api_hashes (abs_path, size, mtime_ms, sha256) VALUES (?, ?, ?, ?)
218 ON CONFLICT(abs_path) DO UPDATE SET size = excluded.size, mtime_ms = excluded.mtime_ms, sha256 = excluded.sha256`)
219 .run([abs, stat.size, Math.floor(stat.mtimeMs), sha]);
220 }
221
222 async function computeSha256 (abs)
223 {
224 const h = crypto.createHash('sha256');
225 await pipeline(fs.createReadStream(abs), h);
226 return h.digest('hex');
227 }
228
229 function entryJson (rootId, rel, stat, abs)
230 {
231 const e = syncIndex.entryFromStat(rel, stat);
232 const out = {
233 id: e.file_id,
234 path: '/' + (rel ? `${rootId}/${rel}` : rootId),
235 name: rel ? path.posix.basename(rel) : rootId,
236 type: e.is_dir ? 'folder' : 'file',
237 size: e.size,
238 mtime: new Date(e.mtime_ms).toISOString(),
239 mtime_ms: e.mtime_ms,
240 version: e.version,
241 };
242 if (!e.is_dir) out.sha256 = abs ? knownSha256(abs, stat) : null;
243 return out;
244 }
245
246 function currentEntry (p)
247 {
248 const st = lstatOrNull(p.abs);
249 return st ? entryJson(p.root.id, p.rel, st, p.abs) : null;
250 }
251
252 /**
253 * Optimistic concurrency for writes to `p`:
254 * - If-None-Match: * -> target must not exist (412)
255 * - If-Match: <ver> -> target must exist with that version (412)
256 * - neither -> 409 when the target exists, unless overwrite=true
257 */
258 function checkPreconditions (p, { ifMatch, ifNoneMatch, overwrite })
259 {
260 const st = lstatOrNull(p.abs);
261 const current = st ? entryJson(p.root.id, p.rel, st, p.abs) : null;
262 if (ifNoneMatch === '*' && st) throw new ApiError(412, 'precondition_failed', 'Target already exists.', { current });
263 if (ifMatch)
264 {
265 if (!st) throw new ApiError(412, 'precondition_failed', 'Target no longer exists.', { current: null });
266 if (ifMatch !== '*' && ifMatch !== current.version) throw new ApiError(412, 'precondition_failed', 'Target was changed by someone else.', { current });
267 }
268 if (st && st.isDirectory()) throw new ApiError(409, 'conflict', 'A folder exists at this path.', { current });
269 if (st && !ifMatch && !overwrite) throw new ApiError(409, 'conflict', 'Target exists. Send If-Match with its version, or overwrite=true.', { current });
270 return st;
271 }
272
273 function requireParentFolder (p)
274 {
275 const parent = path.dirname(p.abs);
276 const st = lstatOrNull(parent);
277 if (!st || !st.isDirectory()) throw new ApiError(409, 'parent_missing', 'Parent folder does not exist.');
278 }
279
280 function boolParam (v)
281 {
282 return v === true || v === 'true' || v === '1' || v === 1;
283 }
284
285 function parseMtime (v)
286 {
287 if (v == null || v === '') return null;
288 const n = Number(v);
289 if (Number.isFinite(n) && n > 0) return n;
290 const d = Date.parse(String(v));
291 if (Number.isFinite(d)) return d;
292 throw new ApiError(400, 'invalid_request', 'mtime must be epoch milliseconds or an ISO date.');
293 }
294
295 function recordUploadMeta (abs, username)
296 {
297 const db = getDb();
298 const uploadedAt = new Date().toISOString();
299 const existing = db.prepare('SELECT file_path FROM file_meta WHERE file_path = ?').get([abs]);
300 if (existing)
301 {
302 db.prepare('UPDATE file_meta SET uploader = ?, sha256 = NULL, uploaded_at = ? WHERE file_path = ?').run([username, uploadedAt, abs]);
303 } else
304 {
305 db.prepare('INSERT INTO file_meta (file_path, uploader, downloaders, watched_by, uploaded_at, sha256) VALUES (?, ?, ?, ?, ?, ?)')
306 .run([abs, username, '[]', '{}', uploadedAt, null]);
307 }
308 try { enqueueFileHash(abs); } catch { /* best effort */ }
309 Promise.resolve().then(() => reindexDirectoryTree(path.dirname(abs))).catch(() => {});
310 }
311
312 function tempPathIn (dir)
313 {
314 return path.join(dir, `${syncIndex.TEMP_PREFIX}${crypto.randomBytes(8).toString('hex')}.part`);
315 }
316
317 function limitStream (max, onTooBig)
318 {
319 let total = 0;
320 return new Transform({
321 transform (chunk, enc, cb)
322 {
323 total += chunk.length;
324 if (total > max) return cb(onTooBig());
325 cb(null, chunk);
326 },
327 });
328 }
329
330 /** Move a finished temp file into place atomically and apply mtime. */
331 function finalizeFile (tempAbs, p, mtimeMs)
332 {
333 if (mtimeMs)
334 {
335 const t = new Date(mtimeMs);
336 fs.utimesSync(tempAbs, t, t);
337 }
338 fs.renameSync(tempAbs, p.abs);
339 }
340
341 function checkQuota (p, addedBytes)
342 {
343 if (!p.info || !p.info.isUserFolder) return;
344 const msg = helpers.checkUserFolderSizeLimit(p.config, p.reqUsername, addedBytes);
345 if (msg) throw new ApiError(507, 'quota_exceeded', msg);
346 }
347
348 // ---------------------------------------------------------------------------
349 // Routes
350 // ---------------------------------------------------------------------------
351
352 router.use((req, res, next) =>
353 {
354 res.set('Access-Control-Allow-Origin', '*');
355 res.set('Access-Control-Allow-Headers', 'Authorization, Content-Type, If-Match, If-None-Match, Range, If-Range, Upload-Offset, X-Mtime');
356 res.set('Access-Control-Allow-Methods', 'GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS');
357 res.set('Access-Control-Expose-Headers', 'ETag, Content-Range, Accept-Ranges, Upload-Offset, Location, Content-Length');
358 if (req.method === 'OPTIONS') return res.status(204).end();
359 next();
360 });
361
362 router.get('/', (req, res) =>
363 {
364 res.json({ name: 'filemanager', api: 'v1', openapi: '/api/v1/openapi.json', oauth: '/.well-known/oauth-authorization-server' });
365 });
366
367 router.get('/openapi.json', (req, res) =>
368 {
369 res.sendFile(path.join(__dirname, '../../docs/openapi.json'));
370 });
371
372 router.use(authenticate);
373
374 router.get('/me', (req, res) =>
375 {
376 const { config, list } = rootsForUser(req.user);
377 const a = apiConfig(config);
378 res.json({
379 username: req.user.username,
380 scopes: req.apiScopes,
381 grant: { id: req.apiGrant.id, kind: req.apiGrant.kind, name: req.apiGrant.name },
382 roots: list.map((r) => ({ id: r.id, name: r.name, writable: r.writable && req.apiScopes.includes('files:write') })),
383 limits: { maxUploadBytes: a.maxUploadBytes, maxChunkBytes: a.maxChunkBytes, maxListLimit: 1000, maxDeltaLimit: 1000 },
384 trash: false,
385 });
386 });
387
388 router.get('/roots', requireScope('files:read'), (req, res) =>
389 {
390 const { list } = rootsForUser(req.user);
391 res.json({ roots: list.map((r) => ({ id: r.id, name: r.name, path: '/' + r.id, writable: r.writable && req.apiScopes.includes('files:write') })) });
392 });
393
394 router.get('/files/metadata', requireScope('files:read'), wrap(async (req, res) =>
395 {
396 const p = resolvePath(req.user, req.query.path);
397 const st = lstatOrNull(p.abs);
398 if (!st || st.isSymbolicLink()) throw new ApiError(404, 'not_found', 'Not found.');
399 if (boolParam(req.query.hash) && st.isFile() && !knownSha256(p.abs, st))
400 {
401 const a = apiConfig(p.config);
402 if (st.size > a.maxHashBytes) throw new ApiError(413, 'too_large', `Hashing on demand is limited to ${a.maxHashBytes} bytes.`);
403 const sha = await computeSha256(p.abs);
404 const st2 = lstatOrNull(p.abs);
405 if (st2 && st2.size === st.size && st2.mtimeMs === st.mtimeMs) rememberSha256(p.abs, st2, sha);
406 }
407 const e = currentEntry(p);
408 res.set('ETag', `"${e.version}"`);
409 res.json(e);
410 }));
411
412 router.get('/files/list', requireScope('files:read'), wrap(async (req, res) =>
413 {
414 const p = resolvePath(req.user, req.query.path);
415 const st = lstatOrNull(p.abs);
416 if (!st) throw new ApiError(404, 'not_found', 'Not found.');
417 if (!st.isDirectory()) throw new ApiError(400, 'not_a_folder', 'Path is not a folder.');
418 const limit = Math.max(1, Math.min(1000, Number(req.query.limit) || 500));
419 const offset = Math.max(0, Number(req.query.page_token) || 0);
420 const names = (await fs.promises.readdir(p.abs)).filter((n) => !syncIndex.isIgnoredName(n)).sort();
421 const page = names.slice(offset, offset + limit);
422 const entries = [];
423 for (const n of page)
424 {
425 const childAbs = path.join(p.abs, n);
426 const cst = lstatOrNull(childAbs);
427 if (!cst || cst.isSymbolicLink() || (!cst.isFile() && !cst.isDirectory())) continue;
428 entries.push(entryJson(p.root.id, p.rel ? `${p.rel}/${n}` : n, cst, childAbs));
429 }
430 const next = offset + limit < names.length ? String(offset + limit) : null;
431 res.json({ folder: currentEntry(p), entries, next_page_token: next });
432 }));
433
434 function downloadHandler (req, res)
435 {
436 let p;
437 try { p = resolvePath(req.user, req.query.path); } catch (err) { return sendError(res, err); }
438 const st = lstatOrNull(p.abs);
439 if (!st || !st.isFile()) return sendError(res, new ApiError(st ? 400 : 404, st ? 'not_a_file' : 'not_found', st ? 'Path is not a file.' : 'Not found.'));
440 const e = entryJson(p.root.id, p.rel, st, p.abs);
441 res.set('ETag', `"${e.version}"`);
442 res.set('X-File-Id', e.id);
443 if (e.sha256) res.set('Digest', `sha-256=${Buffer.from(e.sha256, 'hex').toString('base64')}`);
444 res.set('Content-Disposition', `attachment; filename*=UTF-8''${encodeURIComponent(e.name)}`);
445 const inm = String(req.get('if-none-match') || '').split(',').map(parseEtag);
446 if (inm.includes(e.version) || inm.includes('*')) return res.status(304).end();
447 res.sendFile(p.abs, { dotfiles: 'allow', etag: false, lastModified: true, acceptRanges: true, cacheControl: false }, (err) =>
448 {
449 if (err && !res.headersSent) sendError(res, new ApiError(err.status || 500, 'download_failed', 'Download failed.'));
450 });
451 }
452
453 router.get('/files/content', requireScope('files:read'), downloadHandler);
454 router.head('/files/content', requireScope('files:read'), downloadHandler);
455
456 router.put('/files/content', requireScope('files:write'), wrap(async (req, res) =>
457 {
458 const p = resolvePath(req.user, req.query.path, { write: true });
459 if (!p.rel) throw new ApiError(400, 'invalid_path', 'Cannot write to a root.');
460 p.reqUsername = req.user.username;
461 const a = apiConfig(p.config);
462 const pre = { ifMatch: parseEtag(req.get('if-match')), ifNoneMatch: parseEtag(req.get('if-none-match')), overwrite: boolParam(req.query.overwrite) };
463 const mtime = parseMtime(req.query.mtime || req.get('x-mtime'));
464 requireParentFolder(p);
465 checkPreconditions(p, pre);
466 const declared = req.get('content-length') != null ? Number(req.get('content-length')) : null;
467 if (declared != null && declared > a.maxUploadBytes) throw new ApiError(413, 'too_large', `Maximum upload size is ${a.maxUploadBytes} bytes; use /uploads for large files.`);
468 if (declared != null) checkQuota(p, declared);
469
470 const temp = tempPathIn(path.dirname(p.abs));
471 const hash = crypto.createHash('sha256');
472 let size = 0;
473 try
474 {
475 await pipeline(
476 req,
477 limitStream(a.maxUploadBytes, () => new ApiError(413, 'too_large', `Maximum upload size is ${a.maxUploadBytes} bytes.`)),
478 new Transform({ transform (chunk, enc, cb) { size += chunk.length; hash.update(chunk); cb(null, chunk); } }),
479 fs.createWriteStream(temp, { flags: 'wx' }),
480 );
481 const sha = hash.digest('hex');
482 const expected = req.get('x-content-sha256');
483 if (expected && expected.toLowerCase() !== sha) throw new ApiError(422, 'checksum_mismatch', 'Uploaded content does not match X-Content-SHA256.');
484 if (declared == null) checkQuota(p, size);
485 checkPreconditions(p, pre); // re-check right before the atomic replace
486 const existed = !!lstatOrNull(p.abs);
487 finalizeFile(temp, p, mtime);
488 const st = fs.lstatSync(p.abs);
489 rememberSha256(p.abs, st, sha);
490 recordUploadMeta(p.abs, req.user.username);
491 syncIndex.markDirty(p.root.abs);
492 const e = entryJson(p.root.id, p.rel, st, p.abs);
493 res.set('ETag', `"${e.version}"`);
494 res.status(existed ? 200 : 201).json(e);
495 } finally
496 {
497 fs.rmSync(temp, { force: true });
498 }
499 }));
500
501 router.post('/folders', requireScope('files:write'), json, wrap(async (req, res) =>
502 {
503 const p = resolvePath(req.user, req.body && req.body.path, { write: true });
504 if (!p.rel) throw new ApiError(409, 'conflict', 'Root already exists.');
505 const st = lstatOrNull(p.abs);
506 if (st)
507 {
508 if (st.isDirectory() && boolParam(req.body.exist_ok)) return res.status(200).json(currentEntry(p));
509 throw new ApiError(409, 'conflict', 'Something already exists at this path.', { current: currentEntry(p) });
510 }
511 if (boolParam(req.body.parents))
512 {
513 fs.mkdirSync(p.abs, { recursive: true });
514 } else
515 {
516 requireParentFolder(p);
517 fs.mkdirSync(p.abs);
518 }
519 syncIndex.markDirty(p.root.abs);
520 res.status(201).json(currentEntry(p));
521 }));
522
523 router.post('/files/move', requireScope('files:write'), json, wrap(async (req, res) =>
524 {
525 const body = req.body || {};
526 const ctx = rootsForUser(req.user);
527 const from = resolvePath(req.user, body.from, { write: true, ctx });
528 const to = resolvePath(req.user, body.to, { write: true, ctx });
529 if (!from.rel || !to.rel) throw new ApiError(400, 'invalid_path', 'Roots cannot be moved or replaced.');
530 const st = lstatOrNull(from.abs);
531 if (!st) throw new ApiError(404, 'not_found', 'Source not found.');
532 const ifMatch = parseEtag(body.if_match || req.get('if-match'));
533 const cur = entryJson(from.root.id, from.rel, st, from.abs);
534 if (ifMatch && ifMatch !== '*' && ifMatch !== cur.version) throw new ApiError(412, 'precondition_failed', 'Source was changed by someone else.', { current: cur });
535 if (from.abs === to.abs) return res.json(cur);
536 if (to.abs.startsWith(from.abs + path.sep)) throw new ApiError(400, 'invalid_path', 'Cannot move a folder into itself.');
537 requireParentFolder(to);
538 const dst = lstatOrNull(to.abs);
539 // Case-only renames on case-insensitive filesystems resolve to the same inode.
540 const sameNode = dst && dst.ino === st.ino && dst.dev === st.dev;
541 if (dst && !sameNode)
542 {
543 if (!boolParam(body.overwrite)) throw new ApiError(409, 'conflict', 'Destination exists.', { current: currentEntry(to) });
544 if (dst.isDirectory() || st.isDirectory()) throw new ApiError(409, 'conflict', 'Folders are never overwritten.', { current: currentEntry(to) });
545 }
546 if (to.info && to.info.isUserFolder && from.root.abs !== to.root.abs)
547 {
548 to.reqUsername = req.user.username;
549 checkQuota(to, st.isDirectory() ? 0 : st.size);
550 }
551 helpers.movePathWithFallback(from.abs, to.abs);
552 helpers.rewriteMetaPaths(from.abs, to.abs);
553 try { rewriteIndexPaths(from.abs, to.abs); } catch { /* best effort */ }
554 getDb().prepare('DELETE FROM api_hashes WHERE abs_path = ?').run([from.abs]);
555 syncIndex.markDirty(from.root.abs);
556 syncIndex.markDirty(to.root.abs);
557 res.json(currentEntry(to));
558 }));
559
560 router.delete('/files', requireScope('files:write'), wrap(async (req, res) =>
561 {
562 const p = resolvePath(req.user, req.query.path, { write: true });
563 if (!p.rel) throw new ApiError(400, 'invalid_path', 'Roots cannot be deleted.');
564 if (p.ctx.roots.map((r) => path.resolve(r)).includes(path.resolve(p.abs))) throw new ApiError(400, 'invalid_path', 'Configured roots cannot be deleted.');
565 const st = lstatOrNull(p.abs);
566 if (!st) throw new ApiError(404, 'not_found', 'Not found.');
567 const ifMatch = parseEtag(req.get('if-match'));
568 const cur = entryJson(p.root.id, p.rel, st, p.abs);
569 if (ifMatch && ifMatch !== '*' && ifMatch !== cur.version) throw new ApiError(412, 'precondition_failed', 'Target was changed by someone else.', { current: cur });
570 if (st.isDirectory())
571 {
572 const children = fs.readdirSync(p.abs);
573 if (children.length && !boolParam(req.query.recursive)) throw new ApiError(409, 'folder_not_empty', 'Folder is not empty; pass recursive=true.');
574 fs.rmSync(p.abs, { recursive: true, force: true });
575 } else
576 {
577 fs.unlinkSync(p.abs);
578 }
579 getDb().prepare('DELETE FROM file_meta WHERE file_path = ? OR file_path LIKE ?').run([p.abs, p.abs + path.sep + '%']);
580 getDb().prepare('DELETE FROM api_hashes WHERE abs_path = ? OR abs_path LIKE ?').run([p.abs, p.abs + path.sep + '%']);
581 try { deleteIndexUnder(p.abs); } catch { /* best effort */ }
582 syncIndex.markDirty(p.root.abs);
583 res.status(204).end();
584 }));
585
586 // ---------------------------------------------------------------------------
587 // Delta / change feed
588 // ---------------------------------------------------------------------------
589
590 function encodeCursor (obj)
591 {
592 return Buffer.from(JSON.stringify(obj)).toString('base64url');
593 }
594
595 function decodeCursor (raw)
596 {
597 try
598 {
599 const c = JSON.parse(Buffer.from(String(raw), 'base64url').toString('utf8'));
600 if (c && typeof c === 'object') return c;
601 } catch { /* fallthrough */ }
602 throw new ApiError(400, 'invalid_cursor', 'Malformed cursor.');
603 }
604
605 function rootTag (root)
606 {
607 return crypto.createHash('sha256').update(root.abs).digest('base64url').slice(0, 12);
608 }
609
610 router.get('/delta', requireScope('files:read'), wrap(async (req, res) =>
611 {
612 const ctx = rootsForUser(req.user);
613 let rootId = req.query.root;
614 let cursor = null;
615 if (req.query.cursor)
616 {
617 cursor = decodeCursor(req.query.cursor);
618 rootId = rootId || cursor.r;
619 }
620 const root = ctx.list.find((r) => r.id === rootId);
621 if (!root) throw new ApiError(404, 'not_found', 'Unknown root; pass root=<id> from /roots.');
622 if (cursor && (cursor.r !== root.id || cursor.k !== rootTag(root))) throw new ApiError(400, 'invalid_cursor', 'Cursor belongs to another root.');
623 const a = apiConfig(ctx.config);
624 const limit = Math.max(1, Math.min(1000, Number(req.query.limit) || 500));
625
626 let state;
627 try
628 {
629 state = await syncIndex.ensureFresh(root.abs, root.abs, { intervalMs: a.scanIntervalSeconds * 1000, maxEntries: a.maxSyncEntries });
630 } catch (err)
631 {
632 if (err && err.code === 'too_many_entries') throw new ApiError(507, 'too_many_entries', err.message);
633 throw err;
634 }
635
636 const toPath = (rel) => '/' + (rel ? `${root.id}/${rel}` : root.id);
637 const base = { r: root.id, k: rootTag(root), g: state.generation };
638
639 if (cursor && cursor.g !== state.generation) throw new ApiError(410, 'cursor_expired', 'Cursor is no longer valid; start again without a cursor.');
640
641 if (!cursor || cursor.m === 's')
642 {
643 const seq = cursor ? Number(cursor.s) : syncIndex.currentSeq();
644 const offset = cursor ? Number(cursor.o) || 0 : 0;
645 if (cursor && seq < state.min_seq) throw new ApiError(410, 'cursor_expired', 'Cursor is no longer valid; start again without a cursor.');
646 const rows = syncIndex.listEntries(root.abs, offset, limit);
647 const more = rows.length === limit;
648 return res.json({
649 reset: !cursor,
650 entries: rows.map((r) => ({
651 change: 'exists', id: r.file_id, path: toPath(r.rel_path), type: r.is_dir ? 'folder' : 'file',
652 size: r.size, mtime_ms: r.mtime_ms, version: r.version,
653 })),
654 cursor: encodeCursor(more ? { ...base, m: 's', s: seq, o: offset + rows.length } : { ...base, m: 'c', s: seq }),
655 has_more: more,
656 });
657 }
658
659 const after = Number(cursor.s) || 0;
660 if (after < state.min_seq) throw new ApiError(410, 'cursor_expired', 'Changes since this cursor were pruned; start again without a cursor.');
661 const rows = syncIndex.listChanges(root.abs, after, limit);
662 const last = rows.length ? rows[rows.length - 1].seq : after;
663 res.json({
664 reset: false,
665 entries: rows.map((r) => ({
666 change: r.change, id: r.file_id, path: toPath(r.rel_path),
667 old_path: r.old_rel_path != null ? toPath(r.old_rel_path) : undefined,
668 type: r.is_dir ? 'folder' : 'file',
669 size: r.size, mtime_ms: r.mtime_ms, version: r.version,
670 })),
671 cursor: encodeCursor({ ...base, m: 'c', s: last }),
672 has_more: rows.length === limit,
673 });
674 }));
675
676 // ---------------------------------------------------------------------------
677 // Resumable uploads
678 // ---------------------------------------------------------------------------
679
680 function purgeExpiredUploads (uploadDir)
681 {
682 const d = getDb();
683 const expired = d.prepare('SELECT id FROM api_uploads WHERE expires_at < ?').all([Date.now()]);
684 for (const r of expired)
685 {
686 fs.rmSync(path.join(uploadDir, `${r.id}.part`), { force: true });
687 d.prepare('DELETE FROM api_uploads WHERE id = ?').run([r.id]);
688 }
689 }
690
691 function getUploadFor (req, uploadDir)
692 {
693 const id = String(req.params.id || '');
694 if (!/^[A-Za-z0-9_-]{10,64}$/.test(id)) throw new ApiError(404, 'not_found', 'Upload not found.');
695 const row = getDb().prepare('SELECT * FROM api_uploads WHERE id = ?').get([id]);
696 if (!row || row.username !== req.user.username || row.grant_id !== req.apiGrant.id || row.expires_at < Date.now())
697 {
698 throw new ApiError(404, 'not_found', 'Upload not found or expired.');
699 }
700 row.file = path.join(uploadDir, `${row.id}.part`);
701 return row;
702 }
703
704 function uploadJson (row)
705 {
706 return { id: row.id, path: row.target, size: row.size, offset: row.received, expires_at: new Date(row.expires_at).toISOString() };
707 }
708
709 router.post('/uploads', requireScope('files:write'), json, wrap(async (req, res) =>
710 {
711 const body = req.body || {};
712 const p = resolvePath(req.user, body.path, { write: true });
713 if (!p.rel) throw new ApiError(400, 'invalid_path', 'Cannot write to a root.');
714 p.reqUsername = req.user.username;
715 const a = apiConfig(p.config);
716 const size = Number(body.size);
717 if (!Number.isInteger(size) || size < 0) throw new ApiError(400, 'invalid_request', 'size (bytes) is required.');
718 if (size > a.maxUploadBytes) throw new ApiError(413, 'too_large', `Maximum upload size is ${a.maxUploadBytes} bytes.`);
719 const sha = body.sha256 ? String(body.sha256).toLowerCase() : null;
720 if (sha && !/^[0-9a-f]{64}$/.test(sha)) throw new ApiError(400, 'invalid_request', 'sha256 must be 64 hex characters.');
721 const pre = { ifMatch: parseEtag(body.if_match), ifNoneMatch: body.if_none_match === '*' ? '*' : null, overwrite: boolParam(body.overwrite) };
722 requireParentFolder(p);
723 checkPreconditions(p, pre);
724 checkQuota(p, size);
725
726 fs.mkdirSync(a.uploadDir, { recursive: true, mode: 0o700 });
727 purgeExpiredUploads(a.uploadDir);
728 const open = getDb().prepare('SELECT COUNT(*) AS n FROM api_uploads WHERE username = ?').get([req.user.username]).n;
729 if (open >= a.maxOpenUploadsPerUser) throw new ApiError(429, 'too_many_uploads', 'Too many unfinished uploads; finish or cancel some first.');
730
731 const id = crypto.randomBytes(18).toString('base64url');
732 const t = Date.now();
733 fs.writeFileSync(path.join(a.uploadDir, `${id}.part`), Buffer.alloc(0), { mode: 0o600 });
734 getDb().prepare(`INSERT INTO api_uploads (id, grant_id, username, target, size, received, sha256, mtime_ms, if_match, if_none_match, overwrite, created_at, expires_at)
735 VALUES (?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?)`)
736 .run([id, req.apiGrant.id, req.user.username, p.vpath, size, sha, parseMtime(body.mtime), pre.ifMatch, pre.ifNoneMatch ? 1 : 0, pre.overwrite ? 1 : 0, t, t + a.uploadTtlHours * 3600000]);
737 const row = getDb().prepare('SELECT * FROM api_uploads WHERE id = ?').get([id]);
738 res.set('Location', `/api/v1/uploads/${id}`);
739 res.set('Upload-Offset', '0');
740 res.status(201).json({ ...uploadJson(row), max_chunk_bytes: a.maxChunkBytes });
741 }));
742
743 router.get('/uploads/:id', requireScope('files:write'), wrap(async (req, res) =>
744 {
745 const { config } = helpers.loadConfigAndRoots();
746 const row = getUploadFor(req, apiConfig(config).uploadDir);
747 res.set('Upload-Offset', String(row.received));
748 res.json(uploadJson(row));
749 }));
750
751 router.patch('/uploads/:id', requireScope('files:write'), wrap(async (req, res) =>
752 {
753 const { config } = helpers.loadConfigAndRoots();
754 const a = apiConfig(config);
755 const row = getUploadFor(req, a.uploadDir);
756 const offset = Number(req.get('upload-offset'));
757 if (!Number.isInteger(offset)) throw new ApiError(400, 'invalid_request', 'Upload-Offset header is required.');
758 if (offset !== row.received)
759 {
760 res.set('Upload-Offset', String(row.received));
761 throw new ApiError(409, 'offset_mismatch', `Expected offset ${row.received}.`, { offset: row.received });
762 }
763 const remaining = row.size - row.received;
764 const max = Math.min(a.maxChunkBytes, remaining);
765 let written = 0;
766 try
767 {
768 await pipeline(
769 req,
770 limitStream(max, () => new ApiError(413, 'too_large', `Chunk too large (max ${max} bytes here).`)),
771 new Transform({ transform (chunk, enc, cb) { written += chunk.length; cb(null, chunk); } }),
772 fs.createWriteStream(row.file, { flags: 'r+', start: row.received }),
773 );
774 } catch (err)
775 {
776 // Keep only fully confirmed bytes; a client resumes from the stored offset.
777 fs.truncateSync(row.file, row.received);
778 throw err instanceof ApiError ? err : new ApiError(400, 'upload_interrupted', 'Chunk upload was interrupted.');
779 }
780 const received = row.received + written;
781 getDb().prepare('UPDATE api_uploads SET received = ? WHERE id = ?').run([received, row.id]);
782 res.set('Upload-Offset', String(received));
783 res.json({ ...uploadJson({ ...row, received }) });
784 }));
785
786 router.post('/uploads/:id/complete', requireScope('files:write'), wrap(async (req, res) =>
787 {
788 const { config } = helpers.loadConfigAndRoots();
789 const a = apiConfig(config);
790 const row = getUploadFor(req, a.uploadDir);
791 if (row.received !== row.size) throw new ApiError(409, 'incomplete', `Only ${row.received} of ${row.size} bytes received.`, { offset: row.received });
792 const p = resolvePath(req.user, row.target, { write: true });
793 p.reqUsername = req.user.username;
794 const sha = await computeSha256(row.file);
795 if (row.sha256 && row.sha256 !== sha)
796 {
797 fs.rmSync(row.file, { force: true });
798 getDb().prepare('DELETE FROM api_uploads WHERE id = ?').run([row.id]);
799 throw new ApiError(422, 'checksum_mismatch', 'Uploaded content does not match sha256; upload discarded.');
800 }
801 requireParentFolder(p);
802 const pre = { ifMatch: row.if_match, ifNoneMatch: row.if_none_match ? '*' : null, overwrite: !!row.overwrite };
803 checkPreconditions(p, pre);
804 checkQuota(p, row.size);
805
806 const temp = tempPathIn(path.dirname(p.abs));
807 try
808 {
809 try { fs.renameSync(row.file, temp); } catch { fs.copyFileSync(row.file, temp); fs.rmSync(row.file, { force: true }); }
810 checkPreconditions(p, pre);
811 const existed = !!lstatOrNull(p.abs);
812 finalizeFile(temp, p, row.mtime_ms);
813 getDb().prepare('DELETE FROM api_uploads WHERE id = ?').run([row.id]);
814 const st = fs.lstatSync(p.abs);
815 rememberSha256(p.abs, st, sha);
816 recordUploadMeta(p.abs, req.user.username);
817 syncIndex.markDirty(p.root.abs);
818 const e = entryJson(p.root.id, p.rel, st, p.abs);
819 res.set('ETag', `"${e.version}"`);
820 res.status(existed ? 200 : 201).json(e);
821 } catch (err)
822 {
823 // Lost a race after staging (target changed meanwhile): discard; the client starts a new upload.
824 fs.rmSync(temp, { force: true });
825 getDb().prepare('DELETE FROM api_uploads WHERE id = ?').run([row.id]);
826 throw err;
827 }
828 }));
829
830 router.delete('/uploads/:id', requireScope('files:write'), wrap(async (req, res) =>
831 {
832 const { config } = helpers.loadConfigAndRoots();
833 const row = getUploadFor(req, apiConfig(config).uploadDir);
834 fs.rmSync(row.file, { force: true });
835 getDb().prepare('DELETE FROM api_uploads WHERE id = ?').run([row.id]);
836 res.status(204).end();
837 }));
838
839 router.use((req, res) => res.status(404).json({ error: 'not_found', message: 'Unknown API endpoint.' }));
840
841 router.ApiError = ApiError;
842 module.exports = router;
@@ -0,0 +1,842 @@
1'use strict';
2
3// Public, versioned file API for sync clients (phones, desktops, services).
4// Auth: Bearer access tokens from /oauth/token or personal access tokens.
5// Every request is checked with the same permission helpers as the web UI,
6// so a token can never see or change more than its user.
7
8const express = require('express');
9const fs = require('fs');
10const path = require('path');
11const crypto = require('crypto');
12const { pipeline } = require('stream/promises');
13const { Transform } = require('stream');
14
15const store = require('./store');
16const syncIndex = require('./sync-index');
17const { getDb } = require('../db');
18const { getClientIp } = require('../auth');
19const { logError } = require('../logger');
20const filesRouter = require('../routes/files');
21const { deleteIndexUnder, rewriteIndexPaths, reindexDirectoryTree } = require('../search-index');
22const { enqueueFileHash } = require('../file-hash-queue');
23
24const helpers = filesRouter.helpers;
25const router = express.Router();
26const json = express.json({ limit: '256kb' });
27
28const USER_ROOT_ID = '~';
29const GB = 1024 ** 3;
30const MB = 1024 ** 2;
31const DEFAULTS = {
32 maxUploadBytes: 10 * GB,
33 maxChunkBytes: 64 * MB,
34 maxOpenUploadsPerUser: 20,
35 uploadTtlHours: 24,
36 maxHashBytes: 4 * GB,
37 scanIntervalSeconds: 15,
38 maxSyncEntries: 500000,
39};
40const API_UPLOAD_DIR_DEFAULT = path.join(__dirname, '../../api-uploads');
41
42// ---------------------------------------------------------------------------
43// Helpers
44// ---------------------------------------------------------------------------
45
46class ApiError extends Error
47{
48 constructor (status, code, message, extra)
49 {
50 super(message);
51 this.status = status;
52 this.code = code;
53 this.extra = extra;
54 }
55}
56
57function apiConfig (config)
58{
59 const raw = config && typeof config.api === 'object' && config.api ? config.api : {};
60 const out = { ...DEFAULTS };
61 for (const k of Object.keys(DEFAULTS))
62 {
63 const v = Number(raw[k]);
64 if (Number.isFinite(v) && v > 0) out[k] = v;
65 }
66 out.uploadDir = typeof raw.uploadDir === 'string' && raw.uploadDir.trim() ? raw.uploadDir.trim() : API_UPLOAD_DIR_DEFAULT;
67 return out;
68}
69
70function sendError (res, err)
71{
72 if (!(err instanceof ApiError))
73 {
74 logError('API v1 request failed', err);
75 err = new ApiError(500, 'internal_error', 'Internal server error.');
76 }
77 if (res.headersSent) { res.destroy(); return; }
78 res.status(err.status).json({ error: err.code, message: err.message, ...(err.extra || {}) });
79}
80
81const wrap = (fn) => (req, res) => Promise.resolve(fn(req, res)).catch((err) => sendError(res, err));
82
83function parseEtag (value)
84{
85 const v = String(value || '').trim();
86 if (!v) return null;
87 return v.replace(/^W\//, '').replace(/^"|"$/g, '');
88}
89
90function loadApiUser (username)
91{
92 const row = getDb().prepare('SELECT id, username, is_admin, permissions FROM users WHERE username = ?').get([username]);
93 if (!row) return null;
94 let permissions = {};
95 try { permissions = JSON.parse(row.permissions || '{}'); } catch { permissions = {}; }
96 return { id: row.id, username: row.username, isAdmin: row.is_admin === 1, permissions };
97}
98
99function authenticate (req, res, next)
100{
101 const header = req.get('authorization') || '';
102 const token = header.startsWith('Bearer ') ? header.slice(7).trim() : '';
103 const resolved = store.resolveBearer(token);
104 const user = resolved ? loadApiUser(resolved.grant.username) : null;
105 if (!resolved || !user)
106 {
107 res.set('WWW-Authenticate', 'Bearer error="invalid_token"');
108 return res.status(401).json({ error: 'invalid_token', message: 'Missing, invalid, expired or revoked access token.' });
109 }
110 store.touchGrant(resolved.grant.id, getClientIp(req));
111 req.user = user;
112 req.apiGrant = resolved.grant;
113 req.apiScopes = resolved.scopes;
114 next();
115}
116
117function requireScope (scope)
118{
119 return (req, res, next) =>
120 {
121 if (!req.apiScopes.includes(scope))
122 {
123 res.set('WWW-Authenticate', `Bearer error="insufficient_scope", scope="${scope}"`);
124 return res.status(403).json({ error: 'insufficient_scope', message: `This token lacks the ${scope} scope.` });
125 }
126 next();
127 };
128}
129
130/** Roots visible to the user, keyed by a stable id used in virtual paths. */
131function rootsForUser (user)
132{
133 const { config, roots } = helpers.loadConfigAndRoots();
134 const aliases = config.rootAliases && typeof config.rootAliases === 'object' ? config.rootAliases : {};
135 const list = [];
136 const userFolder = helpers.getUserFolderPath(config, user.username);
137 if (userFolder)
138 {
139 try { fs.mkdirSync(userFolder, { recursive: true }); } catch { /* non-fatal */ }
140 list.push({ id: USER_ROOT_ID, name: 'My Folder', abs: path.resolve(userFolder), writable: true, isUserFolder: true });
141 }
142 const seen = new Set(list.map((r) => r.id));
143 for (const r of roots)
144 {
145 const label = path.basename(r);
146 if (!helpers.canRead(user, label) || seen.has(label)) continue;
147 const info = helpers.resolveRootForUser(r, roots, user, config);
148 seen.add(label);
149 list.push({
150 id: label,
151 name: String(aliases[path.resolve(r)] || '').trim() || label,
152 abs: path.resolve(r),
153 writable: !!(info && helpers.canWriteInfo(user, info)),
154 isUserFolder: false,
155 });
156 }
157 return { config, roots, list };
158}
159
160function validSegment (s)
161{
162 return s && s !== '.' && s !== '..' && !s.includes('\0') && !s.includes('\\') && Buffer.byteLength(s) <= 255;
163}
164
165/**
166 * Resolve a virtual path ("/<root>/a/b") for the user. Throws ApiError.
167 * Returns { root, rel, abs, vpath, config, info }.
168 */
169function resolvePath (user, vpath, { write = false, ctx } = {})
170{
171 const raw = String(vpath == null ? '' : vpath);
172 if (!raw.startsWith('/')) throw new ApiError(400, 'invalid_path', 'Paths must start with /<root-id>/.');
173 if (raw.length > 4096) throw new ApiError(400, 'invalid_path', 'Path too long.');
174 const parts = raw.split('/').slice(1).filter((p, i, arr) => !(p === '' && i === arr.length - 1));
175 if (!parts.length || parts.some((p) => !validSegment(p))) throw new ApiError(400, 'invalid_path', 'Invalid path segment.');
176 const c = ctx || rootsForUser(user);
177 const root = c.list.find((r) => r.id === parts[0]);
178 if (!root) throw new ApiError(404, 'not_found', 'No such root.');
179 const rel = parts.slice(1).join('/');
180 const abs = rel ? path.join(root.abs, ...parts.slice(1)) : root.abs;
181
182 // Same checks as the web UI, so the API can never exceed the user's rights.
183 const info = helpers.resolveRootForUser(abs, c.roots, user, c.config);
184 if (!info || !helpers.canReadInfo(user, info)) throw new ApiError(404, 'not_found', 'Not found.');
185 if (write && !helpers.canWriteInfo(user, info)) throw new ApiError(403, 'forbidden', 'You do not have write access here.');
186
187 // Refuse paths that escape the root through symlinks.
188 let probe = abs;
189 while (probe !== root.abs && !fs.existsSync(probe)) probe = path.dirname(probe);
190 try
191 {
192 const realRoot = fs.realpathSync(root.abs);
193 const realProbe = fs.realpathSync(probe);
194 if (realProbe !== realRoot && !realProbe.startsWith(realRoot + path.sep)) throw new ApiError(404, 'not_found', 'Not found.');
195 } catch (err)
196 {
197 if (err instanceof ApiError) throw err;
198 }
199
200 return { root, rel, abs, vpath: '/' + [root.id, ...parts.slice(1)].join('/'), config: c.config, info, ctx: c };
201}
202
203function lstatOrNull (abs)
204{
205 try { return fs.lstatSync(abs); } catch { return null; }
206}
207
208function knownSha256 (abs, stat)
209{
210 const row = getDb().prepare('SELECT size, mtime_ms, sha256 FROM api_hashes WHERE abs_path = ?').get([abs]);
211 if (row && Number(row.size) === stat.size && Number(row.mtime_ms) === Math.floor(stat.mtimeMs)) return row.sha256;
212 return null;
213}
214
215function rememberSha256 (abs, stat, sha)
216{
217 getDb().prepare(`INSERT INTO api_hashes (abs_path, size, mtime_ms, sha256) VALUES (?, ?, ?, ?)
218 ON CONFLICT(abs_path) DO UPDATE SET size = excluded.size, mtime_ms = excluded.mtime_ms, sha256 = excluded.sha256`)
219 .run([abs, stat.size, Math.floor(stat.mtimeMs), sha]);
220}
221
222async function computeSha256 (abs)
223{
224 const h = crypto.createHash('sha256');
225 await pipeline(fs.createReadStream(abs), h);
226 return h.digest('hex');
227}
228
229function entryJson (rootId, rel, stat, abs)
230{
231 const e = syncIndex.entryFromStat(rel, stat);
232 const out = {
233 id: e.file_id,
234 path: '/' + (rel ? `${rootId}/${rel}` : rootId),
235 name: rel ? path.posix.basename(rel) : rootId,
236 type: e.is_dir ? 'folder' : 'file',
237 size: e.size,
238 mtime: new Date(e.mtime_ms).toISOString(),
239 mtime_ms: e.mtime_ms,
240 version: e.version,
241 };
242 if (!e.is_dir) out.sha256 = abs ? knownSha256(abs, stat) : null;
243 return out;
244}
245
246function currentEntry (p)
247{
248 const st = lstatOrNull(p.abs);
249 return st ? entryJson(p.root.id, p.rel, st, p.abs) : null;
250}
251
252/**
253 * Optimistic concurrency for writes to `p`:
254 * - If-None-Match: * -> target must not exist (412)
255 * - If-Match: <ver> -> target must exist with that version (412)
256 * - neither -> 409 when the target exists, unless overwrite=true
257 */
258function checkPreconditions (p, { ifMatch, ifNoneMatch, overwrite })
259{
260 const st = lstatOrNull(p.abs);
261 const current = st ? entryJson(p.root.id, p.rel, st, p.abs) : null;
262 if (ifNoneMatch === '*' && st) throw new ApiError(412, 'precondition_failed', 'Target already exists.', { current });
263 if (ifMatch)
264 {
265 if (!st) throw new ApiError(412, 'precondition_failed', 'Target no longer exists.', { current: null });
266 if (ifMatch !== '*' && ifMatch !== current.version) throw new ApiError(412, 'precondition_failed', 'Target was changed by someone else.', { current });
267 }
268 if (st && st.isDirectory()) throw new ApiError(409, 'conflict', 'A folder exists at this path.', { current });
269 if (st && !ifMatch && !overwrite) throw new ApiError(409, 'conflict', 'Target exists. Send If-Match with its version, or overwrite=true.', { current });
270 return st;
271}
272
273function requireParentFolder (p)
274{
275 const parent = path.dirname(p.abs);
276 const st = lstatOrNull(parent);
277 if (!st || !st.isDirectory()) throw new ApiError(409, 'parent_missing', 'Parent folder does not exist.');
278}
279
280function boolParam (v)
281{
282 return v === true || v === 'true' || v === '1' || v === 1;
283}
284
285function parseMtime (v)
286{
287 if (v == null || v === '') return null;
288 const n = Number(v);
289 if (Number.isFinite(n) && n > 0) return n;
290 const d = Date.parse(String(v));
291 if (Number.isFinite(d)) return d;
292 throw new ApiError(400, 'invalid_request', 'mtime must be epoch milliseconds or an ISO date.');
293}
294
295function recordUploadMeta (abs, username)
296{
297 const db = getDb();
298 const uploadedAt = new Date().toISOString();
299 const existing = db.prepare('SELECT file_path FROM file_meta WHERE file_path = ?').get([abs]);
300 if (existing)
301 {
302 db.prepare('UPDATE file_meta SET uploader = ?, sha256 = NULL, uploaded_at = ? WHERE file_path = ?').run([username, uploadedAt, abs]);
303 } else
304 {
305 db.prepare('INSERT INTO file_meta (file_path, uploader, downloaders, watched_by, uploaded_at, sha256) VALUES (?, ?, ?, ?, ?, ?)')
306 .run([abs, username, '[]', '{}', uploadedAt, null]);
307 }
308 try { enqueueFileHash(abs); } catch { /* best effort */ }
309 Promise.resolve().then(() => reindexDirectoryTree(path.dirname(abs))).catch(() => {});
310}
311
312function tempPathIn (dir)
313{
314 return path.join(dir, `${syncIndex.TEMP_PREFIX}${crypto.randomBytes(8).toString('hex')}.part`);
315}
316
317function limitStream (max, onTooBig)
318{
319 let total = 0;
320 return new Transform({
321 transform (chunk, enc, cb)
322 {
323 total += chunk.length;
324 if (total > max) return cb(onTooBig());
325 cb(null, chunk);
326 },
327 });
328}
329
330/** Move a finished temp file into place atomically and apply mtime. */
331function finalizeFile (tempAbs, p, mtimeMs)
332{
333 if (mtimeMs)
334 {
335 const t = new Date(mtimeMs);
336 fs.utimesSync(tempAbs, t, t);
337 }
338 fs.renameSync(tempAbs, p.abs);
339}
340
341function checkQuota (p, addedBytes)
342{
343 if (!p.info || !p.info.isUserFolder) return;
344 const msg = helpers.checkUserFolderSizeLimit(p.config, p.reqUsername, addedBytes);
345 if (msg) throw new ApiError(507, 'quota_exceeded', msg);
346}
347
348// ---------------------------------------------------------------------------
349// Routes
350// ---------------------------------------------------------------------------
351
352router.use((req, res, next) =>
353{
354 res.set('Access-Control-Allow-Origin', '*');
355 res.set('Access-Control-Allow-Headers', 'Authorization, Content-Type, If-Match, If-None-Match, Range, If-Range, Upload-Offset, X-Mtime');
356 res.set('Access-Control-Allow-Methods', 'GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS');
357 res.set('Access-Control-Expose-Headers', 'ETag, Content-Range, Accept-Ranges, Upload-Offset, Location, Content-Length');
358 if (req.method === 'OPTIONS') return res.status(204).end();
359 next();
360});
361
362router.get('/', (req, res) =>
363{
364 res.json({ name: 'filemanager', api: 'v1', openapi: '/api/v1/openapi.json', oauth: '/.well-known/oauth-authorization-server' });
365});
366
367router.get('/openapi.json', (req, res) =>
368{
369 res.sendFile(path.join(__dirname, '../../docs/openapi.json'));
370});
371
372router.use(authenticate);
373
374router.get('/me', (req, res) =>
375{
376 const { config, list } = rootsForUser(req.user);
377 const a = apiConfig(config);
378 res.json({
379 username: req.user.username,
380 scopes: req.apiScopes,
381 grant: { id: req.apiGrant.id, kind: req.apiGrant.kind, name: req.apiGrant.name },
382 roots: list.map((r) => ({ id: r.id, name: r.name, writable: r.writable && req.apiScopes.includes('files:write') })),
383 limits: { maxUploadBytes: a.maxUploadBytes, maxChunkBytes: a.maxChunkBytes, maxListLimit: 1000, maxDeltaLimit: 1000 },
384 trash: false,
385 });
386});
387
388router.get('/roots', requireScope('files:read'), (req, res) =>
389{
390 const { list } = rootsForUser(req.user);
391 res.json({ roots: list.map((r) => ({ id: r.id, name: r.name, path: '/' + r.id, writable: r.writable && req.apiScopes.includes('files:write') })) });
392});
393
394router.get('/files/metadata', requireScope('files:read'), wrap(async (req, res) =>
395{
396 const p = resolvePath(req.user, req.query.path);
397 const st = lstatOrNull(p.abs);
398 if (!st || st.isSymbolicLink()) throw new ApiError(404, 'not_found', 'Not found.');
399 if (boolParam(req.query.hash) && st.isFile() && !knownSha256(p.abs, st))
400 {
401 const a = apiConfig(p.config);
402 if (st.size > a.maxHashBytes) throw new ApiError(413, 'too_large', `Hashing on demand is limited to ${a.maxHashBytes} bytes.`);
403 const sha = await computeSha256(p.abs);
404 const st2 = lstatOrNull(p.abs);
405 if (st2 && st2.size === st.size && st2.mtimeMs === st.mtimeMs) rememberSha256(p.abs, st2, sha);
406 }
407 const e = currentEntry(p);
408 res.set('ETag', `"${e.version}"`);
409 res.json(e);
410}));
411
412router.get('/files/list', requireScope('files:read'), wrap(async (req, res) =>
413{
414 const p = resolvePath(req.user, req.query.path);
415 const st = lstatOrNull(p.abs);
416 if (!st) throw new ApiError(404, 'not_found', 'Not found.');
417 if (!st.isDirectory()) throw new ApiError(400, 'not_a_folder', 'Path is not a folder.');
418 const limit = Math.max(1, Math.min(1000, Number(req.query.limit) || 500));
419 const offset = Math.max(0, Number(req.query.page_token) || 0);
420 const names = (await fs.promises.readdir(p.abs)).filter((n) => !syncIndex.isIgnoredName(n)).sort();
421 const page = names.slice(offset, offset + limit);
422 const entries = [];
423 for (const n of page)
424 {
425 const childAbs = path.join(p.abs, n);
426 const cst = lstatOrNull(childAbs);
427 if (!cst || cst.isSymbolicLink() || (!cst.isFile() && !cst.isDirectory())) continue;
428 entries.push(entryJson(p.root.id, p.rel ? `${p.rel}/${n}` : n, cst, childAbs));
429 }
430 const next = offset + limit < names.length ? String(offset + limit) : null;
431 res.json({ folder: currentEntry(p), entries, next_page_token: next });
432}));
433
434function downloadHandler (req, res)
435{
436 let p;
437 try { p = resolvePath(req.user, req.query.path); } catch (err) { return sendError(res, err); }
438 const st = lstatOrNull(p.abs);
439 if (!st || !st.isFile()) return sendError(res, new ApiError(st ? 400 : 404, st ? 'not_a_file' : 'not_found', st ? 'Path is not a file.' : 'Not found.'));
440 const e = entryJson(p.root.id, p.rel, st, p.abs);
441 res.set('ETag', `"${e.version}"`);
442 res.set('X-File-Id', e.id);
443 if (e.sha256) res.set('Digest', `sha-256=${Buffer.from(e.sha256, 'hex').toString('base64')}`);
444 res.set('Content-Disposition', `attachment; filename*=UTF-8''${encodeURIComponent(e.name)}`);
445 const inm = String(req.get('if-none-match') || '').split(',').map(parseEtag);
446 if (inm.includes(e.version) || inm.includes('*')) return res.status(304).end();
447 res.sendFile(p.abs, { dotfiles: 'allow', etag: false, lastModified: true, acceptRanges: true, cacheControl: false }, (err) =>
448 {
449 if (err && !res.headersSent) sendError(res, new ApiError(err.status || 500, 'download_failed', 'Download failed.'));
450 });
451}
452
453router.get('/files/content', requireScope('files:read'), downloadHandler);
454router.head('/files/content', requireScope('files:read'), downloadHandler);
455
456router.put('/files/content', requireScope('files:write'), wrap(async (req, res) =>
457{
458 const p = resolvePath(req.user, req.query.path, { write: true });
459 if (!p.rel) throw new ApiError(400, 'invalid_path', 'Cannot write to a root.');
460 p.reqUsername = req.user.username;
461 const a = apiConfig(p.config);
462 const pre = { ifMatch: parseEtag(req.get('if-match')), ifNoneMatch: parseEtag(req.get('if-none-match')), overwrite: boolParam(req.query.overwrite) };
463 const mtime = parseMtime(req.query.mtime || req.get('x-mtime'));
464 requireParentFolder(p);
465 checkPreconditions(p, pre);
466 const declared = req.get('content-length') != null ? Number(req.get('content-length')) : null;
467 if (declared != null && declared > a.maxUploadBytes) throw new ApiError(413, 'too_large', `Maximum upload size is ${a.maxUploadBytes} bytes; use /uploads for large files.`);
468 if (declared != null) checkQuota(p, declared);
469
470 const temp = tempPathIn(path.dirname(p.abs));
471 const hash = crypto.createHash('sha256');
472 let size = 0;
473 try
474 {
475 await pipeline(
476 req,
477 limitStream(a.maxUploadBytes, () => new ApiError(413, 'too_large', `Maximum upload size is ${a.maxUploadBytes} bytes.`)),
478 new Transform({ transform (chunk, enc, cb) { size += chunk.length; hash.update(chunk); cb(null, chunk); } }),
479 fs.createWriteStream(temp, { flags: 'wx' }),
480 );
481 const sha = hash.digest('hex');
482 const expected = req.get('x-content-sha256');
483 if (expected && expected.toLowerCase() !== sha) throw new ApiError(422, 'checksum_mismatch', 'Uploaded content does not match X-Content-SHA256.');
484 if (declared == null) checkQuota(p, size);
485 checkPreconditions(p, pre); // re-check right before the atomic replace
486 const existed = !!lstatOrNull(p.abs);
487 finalizeFile(temp, p, mtime);
488 const st = fs.lstatSync(p.abs);
489 rememberSha256(p.abs, st, sha);
490 recordUploadMeta(p.abs, req.user.username);
491 syncIndex.markDirty(p.root.abs);
492 const e = entryJson(p.root.id, p.rel, st, p.abs);
493 res.set('ETag', `"${e.version}"`);
494 res.status(existed ? 200 : 201).json(e);
495 } finally
496 {
497 fs.rmSync(temp, { force: true });
498 }
499}));
500
501router.post('/folders', requireScope('files:write'), json, wrap(async (req, res) =>
502{
503 const p = resolvePath(req.user, req.body && req.body.path, { write: true });
504 if (!p.rel) throw new ApiError(409, 'conflict', 'Root already exists.');
505 const st = lstatOrNull(p.abs);
506 if (st)
507 {
508 if (st.isDirectory() && boolParam(req.body.exist_ok)) return res.status(200).json(currentEntry(p));
509 throw new ApiError(409, 'conflict', 'Something already exists at this path.', { current: currentEntry(p) });
510 }
511 if (boolParam(req.body.parents))
512 {
513 fs.mkdirSync(p.abs, { recursive: true });
514 } else
515 {
516 requireParentFolder(p);
517 fs.mkdirSync(p.abs);
518 }
519 syncIndex.markDirty(p.root.abs);
520 res.status(201).json(currentEntry(p));
521}));
522
523router.post('/files/move', requireScope('files:write'), json, wrap(async (req, res) =>
524{
525 const body = req.body || {};
526 const ctx = rootsForUser(req.user);
527 const from = resolvePath(req.user, body.from, { write: true, ctx });
528 const to = resolvePath(req.user, body.to, { write: true, ctx });
529 if (!from.rel || !to.rel) throw new ApiError(400, 'invalid_path', 'Roots cannot be moved or replaced.');
530 const st = lstatOrNull(from.abs);
531 if (!st) throw new ApiError(404, 'not_found', 'Source not found.');
532 const ifMatch = parseEtag(body.if_match || req.get('if-match'));
533 const cur = entryJson(from.root.id, from.rel, st, from.abs);
534 if (ifMatch && ifMatch !== '*' && ifMatch !== cur.version) throw new ApiError(412, 'precondition_failed', 'Source was changed by someone else.', { current: cur });
535 if (from.abs === to.abs) return res.json(cur);
536 if (to.abs.startsWith(from.abs + path.sep)) throw new ApiError(400, 'invalid_path', 'Cannot move a folder into itself.');
537 requireParentFolder(to);
538 const dst = lstatOrNull(to.abs);
539 // Case-only renames on case-insensitive filesystems resolve to the same inode.
540 const sameNode = dst && dst.ino === st.ino && dst.dev === st.dev;
541 if (dst && !sameNode)
542 {
543 if (!boolParam(body.overwrite)) throw new ApiError(409, 'conflict', 'Destination exists.', { current: currentEntry(to) });
544 if (dst.isDirectory() || st.isDirectory()) throw new ApiError(409, 'conflict', 'Folders are never overwritten.', { current: currentEntry(to) });
545 }
546 if (to.info && to.info.isUserFolder && from.root.abs !== to.root.abs)
547 {
548 to.reqUsername = req.user.username;
549 checkQuota(to, st.isDirectory() ? 0 : st.size);
550 }
551 helpers.movePathWithFallback(from.abs, to.abs);
552 helpers.rewriteMetaPaths(from.abs, to.abs);
553 try { rewriteIndexPaths(from.abs, to.abs); } catch { /* best effort */ }
554 getDb().prepare('DELETE FROM api_hashes WHERE abs_path = ?').run([from.abs]);
555 syncIndex.markDirty(from.root.abs);
556 syncIndex.markDirty(to.root.abs);
557 res.json(currentEntry(to));
558}));
559
560router.delete('/files', requireScope('files:write'), wrap(async (req, res) =>
561{
562 const p = resolvePath(req.user, req.query.path, { write: true });
563 if (!p.rel) throw new ApiError(400, 'invalid_path', 'Roots cannot be deleted.');
564 if (p.ctx.roots.map((r) => path.resolve(r)).includes(path.resolve(p.abs))) throw new ApiError(400, 'invalid_path', 'Configured roots cannot be deleted.');
565 const st = lstatOrNull(p.abs);
566 if (!st) throw new ApiError(404, 'not_found', 'Not found.');
567 const ifMatch = parseEtag(req.get('if-match'));
568 const cur = entryJson(p.root.id, p.rel, st, p.abs);
569 if (ifMatch && ifMatch !== '*' && ifMatch !== cur.version) throw new ApiError(412, 'precondition_failed', 'Target was changed by someone else.', { current: cur });
570 if (st.isDirectory())
571 {
572 const children = fs.readdirSync(p.abs);
573 if (children.length && !boolParam(req.query.recursive)) throw new ApiError(409, 'folder_not_empty', 'Folder is not empty; pass recursive=true.');
574 fs.rmSync(p.abs, { recursive: true, force: true });
575 } else
576 {
577 fs.unlinkSync(p.abs);
578 }
579 getDb().prepare('DELETE FROM file_meta WHERE file_path = ? OR file_path LIKE ?').run([p.abs, p.abs + path.sep + '%']);
580 getDb().prepare('DELETE FROM api_hashes WHERE abs_path = ? OR abs_path LIKE ?').run([p.abs, p.abs + path.sep + '%']);
581 try { deleteIndexUnder(p.abs); } catch { /* best effort */ }
582 syncIndex.markDirty(p.root.abs);
583 res.status(204).end();
584}));
585
586// ---------------------------------------------------------------------------
587// Delta / change feed
588// ---------------------------------------------------------------------------
589
590function encodeCursor (obj)
591{
592 return Buffer.from(JSON.stringify(obj)).toString('base64url');
593}
594
595function decodeCursor (raw)
596{
597 try
598 {
599 const c = JSON.parse(Buffer.from(String(raw), 'base64url').toString('utf8'));
600 if (c && typeof c === 'object') return c;
601 } catch { /* fallthrough */ }
602 throw new ApiError(400, 'invalid_cursor', 'Malformed cursor.');
603}
604
605function rootTag (root)
606{
607 return crypto.createHash('sha256').update(root.abs).digest('base64url').slice(0, 12);
608}
609
610router.get('/delta', requireScope('files:read'), wrap(async (req, res) =>
611{
612 const ctx = rootsForUser(req.user);
613 let rootId = req.query.root;
614 let cursor = null;
615 if (req.query.cursor)
616 {
617 cursor = decodeCursor(req.query.cursor);
618 rootId = rootId || cursor.r;
619 }
620 const root = ctx.list.find((r) => r.id === rootId);
621 if (!root) throw new ApiError(404, 'not_found', 'Unknown root; pass root=<id> from /roots.');
622 if (cursor && (cursor.r !== root.id || cursor.k !== rootTag(root))) throw new ApiError(400, 'invalid_cursor', 'Cursor belongs to another root.');
623 const a = apiConfig(ctx.config);
624 const limit = Math.max(1, Math.min(1000, Number(req.query.limit) || 500));
625
626 let state;
627 try
628 {
629 state = await syncIndex.ensureFresh(root.abs, root.abs, { intervalMs: a.scanIntervalSeconds * 1000, maxEntries: a.maxSyncEntries });
630 } catch (err)
631 {
632 if (err && err.code === 'too_many_entries') throw new ApiError(507, 'too_many_entries', err.message);
633 throw err;
634 }
635
636 const toPath = (rel) => '/' + (rel ? `${root.id}/${rel}` : root.id);
637 const base = { r: root.id, k: rootTag(root), g: state.generation };
638
639 if (cursor && cursor.g !== state.generation) throw new ApiError(410, 'cursor_expired', 'Cursor is no longer valid; start again without a cursor.');
640
641 if (!cursor || cursor.m === 's')
642 {
643 const seq = cursor ? Number(cursor.s) : syncIndex.currentSeq();
644 const offset = cursor ? Number(cursor.o) || 0 : 0;
645 if (cursor && seq < state.min_seq) throw new ApiError(410, 'cursor_expired', 'Cursor is no longer valid; start again without a cursor.');
646 const rows = syncIndex.listEntries(root.abs, offset, limit);
647 const more = rows.length === limit;
648 return res.json({
649 reset: !cursor,
650 entries: rows.map((r) => ({
651 change: 'exists', id: r.file_id, path: toPath(r.rel_path), type: r.is_dir ? 'folder' : 'file',
652 size: r.size, mtime_ms: r.mtime_ms, version: r.version,
653 })),
654 cursor: encodeCursor(more ? { ...base, m: 's', s: seq, o: offset + rows.length } : { ...base, m: 'c', s: seq }),
655 has_more: more,
656 });
657 }
658
659 const after = Number(cursor.s) || 0;
660 if (after < state.min_seq) throw new ApiError(410, 'cursor_expired', 'Changes since this cursor were pruned; start again without a cursor.');
661 const rows = syncIndex.listChanges(root.abs, after, limit);
662 const last = rows.length ? rows[rows.length - 1].seq : after;
663 res.json({
664 reset: false,
665 entries: rows.map((r) => ({
666 change: r.change, id: r.file_id, path: toPath(r.rel_path),
667 old_path: r.old_rel_path != null ? toPath(r.old_rel_path) : undefined,
668 type: r.is_dir ? 'folder' : 'file',
669 size: r.size, mtime_ms: r.mtime_ms, version: r.version,
670 })),
671 cursor: encodeCursor({ ...base, m: 'c', s: last }),
672 has_more: rows.length === limit,
673 });
674}));
675
676// ---------------------------------------------------------------------------
677// Resumable uploads
678// ---------------------------------------------------------------------------
679
680function purgeExpiredUploads (uploadDir)
681{
682 const d = getDb();
683 const expired = d.prepare('SELECT id FROM api_uploads WHERE expires_at < ?').all([Date.now()]);
684 for (const r of expired)
685 {
686 fs.rmSync(path.join(uploadDir, `${r.id}.part`), { force: true });
687 d.prepare('DELETE FROM api_uploads WHERE id = ?').run([r.id]);
688 }
689}
690
691function getUploadFor (req, uploadDir)
692{
693 const id = String(req.params.id || '');
694 if (!/^[A-Za-z0-9_-]{10,64}$/.test(id)) throw new ApiError(404, 'not_found', 'Upload not found.');
695 const row = getDb().prepare('SELECT * FROM api_uploads WHERE id = ?').get([id]);
696 if (!row || row.username !== req.user.username || row.grant_id !== req.apiGrant.id || row.expires_at < Date.now())
697 {
698 throw new ApiError(404, 'not_found', 'Upload not found or expired.');
699 }
700 row.file = path.join(uploadDir, `${row.id}.part`);
701 return row;
702}
703
704function uploadJson (row)
705{
706 return { id: row.id, path: row.target, size: row.size, offset: row.received, expires_at: new Date(row.expires_at).toISOString() };
707}
708
709router.post('/uploads', requireScope('files:write'), json, wrap(async (req, res) =>
710{
711 const body = req.body || {};
712 const p = resolvePath(req.user, body.path, { write: true });
713 if (!p.rel) throw new ApiError(400, 'invalid_path', 'Cannot write to a root.');
714 p.reqUsername = req.user.username;
715 const a = apiConfig(p.config);
716 const size = Number(body.size);
717 if (!Number.isInteger(size) || size < 0) throw new ApiError(400, 'invalid_request', 'size (bytes) is required.');
718 if (size > a.maxUploadBytes) throw new ApiError(413, 'too_large', `Maximum upload size is ${a.maxUploadBytes} bytes.`);
719 const sha = body.sha256 ? String(body.sha256).toLowerCase() : null;
720 if (sha && !/^[0-9a-f]{64}$/.test(sha)) throw new ApiError(400, 'invalid_request', 'sha256 must be 64 hex characters.');
721 const pre = { ifMatch: parseEtag(body.if_match), ifNoneMatch: body.if_none_match === '*' ? '*' : null, overwrite: boolParam(body.overwrite) };
722 requireParentFolder(p);
723 checkPreconditions(p, pre);
724 checkQuota(p, size);
725
726 fs.mkdirSync(a.uploadDir, { recursive: true, mode: 0o700 });
727 purgeExpiredUploads(a.uploadDir);
728 const open = getDb().prepare('SELECT COUNT(*) AS n FROM api_uploads WHERE username = ?').get([req.user.username]).n;
729 if (open >= a.maxOpenUploadsPerUser) throw new ApiError(429, 'too_many_uploads', 'Too many unfinished uploads; finish or cancel some first.');
730
731 const id = crypto.randomBytes(18).toString('base64url');
732 const t = Date.now();
733 fs.writeFileSync(path.join(a.uploadDir, `${id}.part`), Buffer.alloc(0), { mode: 0o600 });
734 getDb().prepare(`INSERT INTO api_uploads (id, grant_id, username, target, size, received, sha256, mtime_ms, if_match, if_none_match, overwrite, created_at, expires_at)
735 VALUES (?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?)`)
736 .run([id, req.apiGrant.id, req.user.username, p.vpath, size, sha, parseMtime(body.mtime), pre.ifMatch, pre.ifNoneMatch ? 1 : 0, pre.overwrite ? 1 : 0, t, t + a.uploadTtlHours * 3600000]);
737 const row = getDb().prepare('SELECT * FROM api_uploads WHERE id = ?').get([id]);
738 res.set('Location', `/api/v1/uploads/${id}`);
739 res.set('Upload-Offset', '0');
740 res.status(201).json({ ...uploadJson(row), max_chunk_bytes: a.maxChunkBytes });
741}));
742
743router.get('/uploads/:id', requireScope('files:write'), wrap(async (req, res) =>
744{
745 const { config } = helpers.loadConfigAndRoots();
746 const row = getUploadFor(req, apiConfig(config).uploadDir);
747 res.set('Upload-Offset', String(row.received));
748 res.json(uploadJson(row));
749}));
750
751router.patch('/uploads/:id', requireScope('files:write'), wrap(async (req, res) =>
752{
753 const { config } = helpers.loadConfigAndRoots();
754 const a = apiConfig(config);
755 const row = getUploadFor(req, a.uploadDir);
756 const offset = Number(req.get('upload-offset'));
757 if (!Number.isInteger(offset)) throw new ApiError(400, 'invalid_request', 'Upload-Offset header is required.');
758 if (offset !== row.received)
759 {
760 res.set('Upload-Offset', String(row.received));
761 throw new ApiError(409, 'offset_mismatch', `Expected offset ${row.received}.`, { offset: row.received });
762 }
763 const remaining = row.size - row.received;
764 const max = Math.min(a.maxChunkBytes, remaining);
765 let written = 0;
766 try
767 {
768 await pipeline(
769 req,
770 limitStream(max, () => new ApiError(413, 'too_large', `Chunk too large (max ${max} bytes here).`)),
771 new Transform({ transform (chunk, enc, cb) { written += chunk.length; cb(null, chunk); } }),
772 fs.createWriteStream(row.file, { flags: 'r+', start: row.received }),
773 );
774 } catch (err)
775 {
776 // Keep only fully confirmed bytes; a client resumes from the stored offset.
777 fs.truncateSync(row.file, row.received);
778 throw err instanceof ApiError ? err : new ApiError(400, 'upload_interrupted', 'Chunk upload was interrupted.');
779 }
780 const received = row.received + written;
781 getDb().prepare('UPDATE api_uploads SET received = ? WHERE id = ?').run([received, row.id]);
782 res.set('Upload-Offset', String(received));
783 res.json({ ...uploadJson({ ...row, received }) });
784}));
785
786router.post('/uploads/:id/complete', requireScope('files:write'), wrap(async (req, res) =>
787{
788 const { config } = helpers.loadConfigAndRoots();
789 const a = apiConfig(config);
790 const row = getUploadFor(req, a.uploadDir);
791 if (row.received !== row.size) throw new ApiError(409, 'incomplete', `Only ${row.received} of ${row.size} bytes received.`, { offset: row.received });
792 const p = resolvePath(req.user, row.target, { write: true });
793 p.reqUsername = req.user.username;
794 const sha = await computeSha256(row.file);
795 if (row.sha256 && row.sha256 !== sha)
796 {
797 fs.rmSync(row.file, { force: true });
798 getDb().prepare('DELETE FROM api_uploads WHERE id = ?').run([row.id]);
799 throw new ApiError(422, 'checksum_mismatch', 'Uploaded content does not match sha256; upload discarded.');
800 }
801 requireParentFolder(p);
802 const pre = { ifMatch: row.if_match, ifNoneMatch: row.if_none_match ? '*' : null, overwrite: !!row.overwrite };
803 checkPreconditions(p, pre);
804 checkQuota(p, row.size);
805
806 const temp = tempPathIn(path.dirname(p.abs));
807 try
808 {
809 try { fs.renameSync(row.file, temp); } catch { fs.copyFileSync(row.file, temp); fs.rmSync(row.file, { force: true }); }
810 checkPreconditions(p, pre);
811 const existed = !!lstatOrNull(p.abs);
812 finalizeFile(temp, p, row.mtime_ms);
813 getDb().prepare('DELETE FROM api_uploads WHERE id = ?').run([row.id]);
814 const st = fs.lstatSync(p.abs);
815 rememberSha256(p.abs, st, sha);
816 recordUploadMeta(p.abs, req.user.username);
817 syncIndex.markDirty(p.root.abs);
818 const e = entryJson(p.root.id, p.rel, st, p.abs);
819 res.set('ETag', `"${e.version}"`);
820 res.status(existed ? 200 : 201).json(e);
821 } catch (err)
822 {
823 // Lost a race after staging (target changed meanwhile): discard; the client starts a new upload.
824 fs.rmSync(temp, { force: true });
825 getDb().prepare('DELETE FROM api_uploads WHERE id = ?').run([row.id]);
826 throw err;
827 }
828}));
829
830router.delete('/uploads/:id', requireScope('files:write'), wrap(async (req, res) =>
831{
832 const { config } = helpers.loadConfigAndRoots();
833 const row = getUploadFor(req, apiConfig(config).uploadDir);
834 fs.rmSync(row.file, { force: true });
835 getDb().prepare('DELETE FROM api_uploads WHERE id = ?').run([row.id]);
836 res.status(204).end();
837}));
838
839router.use((req, res) => res.status(404).json({ error: 'not_found', message: 'Unknown API endpoint.' }));
840
841router.ApiError = ApiError;
842module.exports = router;
server/db.js +2 −0
@@ -107,6 +107,8 @@ function initDb ()
107 107 {
108 108 d.exec('ALTER TABLE file_meta ADD COLUMN uploaded_at TEXT');
109 109 }
110
111 require('./api/store').initApiSchema(d);
110 112 }
111 113
112 114 function closeDb ()
@@ -107,6 +107,8 @@ function initDb ()
107 {
107 {
108 d.exec('ALTER TABLE file_meta ADD COLUMN uploaded_at TEXT');
108 d.exec('ALTER TABLE file_meta ADD COLUMN uploaded_at TEXT');
109 }
109 }
110
111 require('./api/store').initApiSchema(d);
110}
112}
111
113
112function closeDb ()
114function closeDb ()
server/index.js +9 −0
@@ -18,10 +18,18 @@ const authRoutes = require('./routes/auth');
18 18 const filesRoutes = require('./routes/files');
19 19 const adminRoutes = require('./routes/admin');
20 20 const shareRoutes = require('./routes/share');
21 const oauthRoutes = require('./api/oauth');
22 const apiV1Routes = require('./api/v1');
23 const apiAccountRoutes = require('./api/manage');
21 24 const { startShareMaintenanceLoop, stopShareMaintenanceLoop } = require('./routes/share');
22 25
23 26 const app = express();
24 27
28 // Public sync API and OAuth endpoints. Mounted before the global JSON parser
29 // so raw uploads are streamed untouched.
30 app.use(oauthRoutes);
31 app.use('/api/v1', apiV1Routes);
32
25 33 app.use(express.json({ limit: '50mb' }));
26 34 app.use('/vendor/video.js', express.static(path.join(__dirname, '../node_modules/video.js/dist')));
27 35 app.use(express.static(path.join(__dirname, '../public')));
@@ -30,6 +38,7 @@ app.use('/api/auth', authRoutes);
30 38 app.use('/api/files', filesRoutes);
31 39 app.use('/api/admin', adminRoutes);
32 40 app.use('/api/share', shareRoutes);
41 app.use('/api/account/api-access', apiAccountRoutes);
33 42
34 43 app.use((err, req, res, next) =>
35 44 {
@@ -18,10 +18,18 @@ const authRoutes = require('./routes/auth');
18const filesRoutes = require('./routes/files');
18const filesRoutes = require('./routes/files');
19const adminRoutes = require('./routes/admin');
19const adminRoutes = require('./routes/admin');
20const shareRoutes = require('./routes/share');
20const shareRoutes = require('./routes/share');
21const oauthRoutes = require('./api/oauth');
22const apiV1Routes = require('./api/v1');
23const apiAccountRoutes = require('./api/manage');
21const { startShareMaintenanceLoop, stopShareMaintenanceLoop } = require('./routes/share');
24const { startShareMaintenanceLoop, stopShareMaintenanceLoop } = require('./routes/share');
22
25
23const app = express();
26const app = express();
24
27
28// Public sync API and OAuth endpoints. Mounted before the global JSON parser
29// so raw uploads are streamed untouched.
30app.use(oauthRoutes);
31app.use('/api/v1', apiV1Routes);
32
25app.use(express.json({ limit: '50mb' }));
33app.use(express.json({ limit: '50mb' }));
26app.use('/vendor/video.js', express.static(path.join(__dirname, '../node_modules/video.js/dist')));
34app.use('/vendor/video.js', express.static(path.join(__dirname, '../node_modules/video.js/dist')));
27app.use(express.static(path.join(__dirname, '../public')));
35app.use(express.static(path.join(__dirname, '../public')));
@@ -30,6 +38,7 @@ app.use('/api/auth', authRoutes);
30app.use('/api/files', filesRoutes);
38app.use('/api/files', filesRoutes);
31app.use('/api/admin', adminRoutes);
39app.use('/api/admin', adminRoutes);
32app.use('/api/share', shareRoutes);
40app.use('/api/share', shareRoutes);
41app.use('/api/account/api-access', apiAccountRoutes);
33
42
34app.use((err, req, res, next) =>
43app.use((err, req, res, next) =>
35{
44{
server/routes/files.js +13 −0
@@ -2473,4 +2473,17 @@ router.post('/copy', requireAuth, async (req, res) =>
2473 2473 res.json({ ok: true, path: dest, conflictResolution: resolvedConflict });
2474 2474 });
2475 2475
2476 // Shared with the sync API (server/api) so both use the same permission rules.
2477 router.helpers = {
2478 loadConfigAndRoots,
2479 resolveRootForUser,
2480 canRead,
2481 canReadInfo,
2482 canWriteInfo,
2483 getUserFolderPath,
2484 checkUserFolderSizeLimit,
2485 rewriteMetaPaths,
2486 movePathWithFallback,
2487 };
2488
2476 2489 module.exports = router;
@@ -2473,4 +2473,17 @@ router.post('/copy', requireAuth, async (req, res) =>
2473 res.json({ ok: true, path: dest, conflictResolution: resolvedConflict });
2473 res.json({ ok: true, path: dest, conflictResolution: resolvedConflict });
2474});
2474});
2475
2475
2476// Shared with the sync API (server/api) so both use the same permission rules.
2477router.helpers = {
2478 loadConfigAndRoots,
2479 resolveRootForUser,
2480 canRead,
2481 canReadInfo,
2482 canWriteInfo,
2483 getUserFolderPath,
2484 checkUserFolderSizeLimit,
2485 rewriteMetaPaths,
2486 movePathWithFallback,
2487};
2488
2476module.exports = router;
2489module.exports = router;
tests/api.v1.test.js added +733 −0
@@ -0,0 +1,733 @@
1 'use strict';
2
3 // Public sync API + OAuth: auth flow, scopes, isolation between users,
4 // uploads/downloads, delta feed and conflict detection.
5
6 const fs = require('fs');
7 const os = require('os');
8 const path = require('path');
9 const http = require('http');
10 const crypto = require('crypto');
11 const express = require('express');
12 const bcrypt = require('bcrypt');
13 const { once } = require('events');
14
15 const mockBase = fs.mkdtempSync(path.join(os.tmpdir(), 'fm-api-'));
16 const mockConfig = {
17 port: 3000,
18 paths: [],
19 userPath: null,
20 rootAliases: {},
21 api: { scanIntervalSeconds: 0.001, maxChunkBytes: 1024 * 1024, uploadDir: null },
22 };
23
24 jest.mock('../server/db', () =>
25 {
26 const { Database } = require('node-sqlite3-wasm');
27 let db;
28 function getDb ()
29 {
30 if (!db)
31 {
32 db = new Database(':memory:');
33 db.exec(`
34 CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, username TEXT UNIQUE NOT NULL, password_hash TEXT NOT NULL,
35 is_admin INTEGER NOT NULL DEFAULT 0, permissions TEXT NOT NULL DEFAULT '{}');
36 CREATE TABLE file_meta (file_path TEXT PRIMARY KEY, uploader TEXT NOT NULL DEFAULT '', downloaders TEXT NOT NULL DEFAULT '[]',
37 watched_by TEXT NOT NULL DEFAULT '{}', uploaded_at TEXT, sha256 TEXT);
38 CREATE TABLE user_last_navigation (username TEXT PRIMARY KEY, last_dir TEXT, updated_at INTEGER NOT NULL);
39 `);
40 }
41 return db;
42 }
43 return { getDb, initDb: () => {}, closeDb: () => {} };
44 });
45
46 jest.mock('../server/config', () =>
47 {
48 const actual = jest.requireActual('../server/config');
49 return { ...actual, loadConfig: () => mockConfig, saveConfig: () => {} };
50 });
51
52 jest.mock('../server/auth', () =>
53 {
54 const actual = jest.requireActual('../server/auth');
55 return {
56 ...actual,
57 // Web-session auth stand-in for the management routes.
58 requireAuth: (req, res, next) =>
59 {
60 const name = req.get('x-test-user');
61 const { getDb } = require('../server/db');
62 const row = name ? getDb().prepare('SELECT * FROM users WHERE username = ?').get([name]) : null;
63 if (!row) return res.status(401).json({ error: 'Session invalid or expired.' });
64 req.user = { id: row.id, username: row.username, isAdmin: row.is_admin === 1, permissions: JSON.parse(row.permissions) };
65 next();
66 },
67 };
68 });
69
70 jest.mock('../server/search-index', () => ({
71 searchFiles: async () => [],
72 deleteIndexPath: () => {},
73 deleteIndexUnder: () => {},
74 rewriteIndexPaths: () => {},
75 reindexDirectoryTree: async () => {},
76 }));
77 jest.mock('../server/file-hash-queue', () => ({ enqueueFileHash: () => {} }));
78 jest.mock('../server/thumbnail-cache', () => ({
79 getCachedThumbnailInfo: async () => null,
80 getFilesWithThumbnailsInDir: async () => [],
81 getFolderIconSourceFile: async () => null,
82 setFolderIconAssignment: () => {},
83 getThumbnailManifestSourcePathSet: async () => new Set(),
84 needsPreviewImageConversion: () => false,
85 streamPreviewImage: async () => {},
86 MAX_PREVIEW_IMAGE_BYTES: 1,
87 THUMB_HTTP_MAX_AGE_SEC: 1,
88 }));
89
90 const { getDb } = require('../server/db');
91 const store = require('../server/api/store');
92 const oauthRoutes = require('../server/api/oauth');
93 const apiV1Routes = require('../server/api/v1');
94 const manageRoutes = require('../server/api/manage');
95
96 const ROOTS = {
97 shared: path.join(mockBase, 'roots', 'shared'),
98 team: path.join(mockBase, 'roots', 'team'),
99 secret: path.join(mockBase, 'roots', 'secret'),
100 };
101 const USERS_DIR = path.join(mockBase, 'users');
102 const REDIRECT = 'https://sync.example.com/callback';
103
104 let server;
105 let base;
106 let client;
107
108 function verifierPair ()
109 {
110 const verifier = crypto.randomBytes(32).toString('base64url');
111 return { verifier, challenge: crypto.createHash('sha256').update(verifier).digest('base64url') };
112 }
113
114 async function req (method, url, { token, headers = {}, body, form, json, redirect = 'manual' } = {})
115 {
116 const h = { ...headers };
117 if (token) h.Authorization = `Bearer ${token}`;
118 let payload = body;
119 if (form) { h['Content-Type'] = 'application/x-www-form-urlencoded'; payload = new URLSearchParams(form).toString(); }
120 if (json !== undefined) { h['Content-Type'] = 'application/json'; payload = JSON.stringify(json); }
121 const res = await fetch(base + url, { method, headers: h, body: payload, redirect });
122 const buf = Buffer.from(await res.arrayBuffer());
123 let data = null;
124 if ((res.headers.get('content-type') || '').includes('json') && buf.length) data = JSON.parse(buf.toString('utf8'));
125 return { status: res.status, headers: res.headers, data, buf, text: buf.toString('utf8') };
126 }
127
128 async function authorize (username, password, scope = 'files:read files:write', extra = {})
129 {
130 const { verifier, challenge } = verifierPair();
131 const params = {
132 response_type: 'code', client_id: client.clientId, redirect_uri: REDIRECT, scope, state: 'st-1',
133 code_challenge: challenge, code_challenge_method: 'S256', device_name: 'Test phone', ...extra,
134 };
135 const r = await req('POST', '/oauth/authorize', { form: { ...params, username, password, decision: 'allow' } });
136 return { r, verifier, params };
137 }
138
139 async function login (username, scope)
140 {
141 const { r, verifier } = await authorize(username, 'pw-' + username, scope);
142 expect(r.status).toBe(302);
143 const code = new URL(r.headers.get('location')).searchParams.get('code');
144 const t = await req('POST', '/oauth/token', { form: { grant_type: 'authorization_code', client_id: client.clientId, code, redirect_uri: REDIRECT, code_verifier: verifier } });
145 expect(t.status).toBe(200);
146 return t.data;
147 }
148
149 function vq (p) { return encodeURIComponent(p); }
150
151 beforeAll(async () =>
152 {
153 for (const r of Object.values(ROOTS)) fs.mkdirSync(r, { recursive: true });
154 fs.mkdirSync(USERS_DIR, { recursive: true });
155 fs.writeFileSync(path.join(ROOTS.secret, 'secret.txt'), 'top secret');
156 fs.writeFileSync(path.join(ROOTS.shared, 'readme.txt'), 'shared readme');
157 mockConfig.paths = Object.values(ROOTS);
158 mockConfig.userPath = USERS_DIR;
159 mockConfig.api.uploadDir = path.join(mockBase, 'staging');
160
161 const d = getDb();
162 store.initApiSchema(d);
163 const hash = (pw) => bcrypt.hashSync(pw, 4);
164 d.prepare('INSERT INTO users (username, password_hash, is_admin, permissions) VALUES (?, ?, ?, ?)')
165 .run(['alice', hash('pw-alice'), 0, JSON.stringify({ shared: { read: true, write: false }, team: { read: true, write: true } })]);
166 d.prepare('INSERT INTO users (username, password_hash, is_admin, permissions) VALUES (?, ?, ?, ?)')
167 .run(['bob', hash('pw-bob'), 0, JSON.stringify({ team: { read: true, write: false } })]);
168 d.prepare('INSERT INTO users (username, password_hash, is_admin, permissions) VALUES (?, ?, ?, ?)')
169 .run(['root', hash('pw-root'), 1, '{}']);
170
171 const app = express();
172 app.use(oauthRoutes);
173 app.use('/api/v1', apiV1Routes);
174 app.use(express.json());
175 app.use('/api/account/api-access', manageRoutes);
176 server = http.createServer(app).listen(0, '127.0.0.1');
177 await once(server, 'listening');
178 base = `http://127.0.0.1:${server.address().port}`;
179 client = store.createClient({ name: 'Sync App', redirectUris: [REDIRECT, 'http://127.0.0.1/cb'], createdBy: 'root' });
180 });
181
182 afterAll(async () =>
183 {
184 server.close();
185 fs.rmSync(mockBase, { recursive: true, force: true });
186 });
187
188 beforeEach(() => oauthRoutes.resetLoginFailures());
189
190 // ---------------------------------------------------------------------------
191
192 describe('OAuth authorization code + PKCE', () =>
193 {
194 test('metadata advertises PKCE S256 and public clients', async () =>
195 {
196 const r = await req('GET', '/.well-known/oauth-authorization-server');
197 expect(r.data.code_challenge_methods_supported).toEqual(['S256']);
198 expect(r.data.token_endpoint_auth_methods_supported).toEqual(['none']);
199 });
200
201 test('consent page shows client, device and scopes and cannot be framed', async () =>
202 {
203 const { challenge } = verifierPair();
204 const q = new URLSearchParams({ response_type: 'code', client_id: client.clientId, redirect_uri: REDIRECT, scope: 'files:read', code_challenge: challenge, code_challenge_method: 'S256', device_name: 'Pixel <8>' });
205 const r = await req('GET', `/oauth/authorize?${q}`);
206 expect(r.status).toBe(200);
207 expect(r.text).toContain('Sync App');
208 expect(r.text).toContain('Pixel &lt;8&gt;');
209 expect(r.text).toContain('files:read');
210 expect(r.headers.get('x-frame-options')).toBe('DENY');
211 });
212
213 test('unknown client or unregistered redirect never redirects', async () =>
214 {
215 const { challenge } = verifierPair();
216 let r = await req('GET', `/oauth/authorize?response_type=code&client_id=nope&redirect_uri=${vq(REDIRECT)}&code_challenge=${challenge}&code_challenge_method=S256`);
217 expect(r.status).toBe(400);
218 r = await req('GET', `/oauth/authorize?response_type=code&client_id=${client.clientId}&redirect_uri=${vq('https://evil.example/cb')}&code_challenge=${challenge}&code_challenge_method=S256`);
219 expect(r.status).toBe(400);
220 });
221
222 test('PKCE is mandatory and only S256', async () =>
223 {
224 let r = await req('GET', `/oauth/authorize?response_type=code&client_id=${client.clientId}&redirect_uri=${vq(REDIRECT)}&state=x`);
225 expect(r.status).toBe(302);
226 expect(new URL(r.headers.get('location')).searchParams.get('error')).toBe('invalid_request');
227 r = await req('GET', `/oauth/authorize?response_type=code&client_id=${client.clientId}&redirect_uri=${vq(REDIRECT)}&code_challenge=${'a'.repeat(43)}&code_challenge_method=plain`);
228 expect(new URL(r.headers.get('location')).searchParams.get('error')).toBe('invalid_request');
229 });
230
231 test('unknown scopes are rejected', async () =>
232 {
233 const { r } = await authorize('alice', 'pw-alice', 'files:read admin');
234 expect(new URL(r.headers.get('location')).searchParams.get('error')).toBe('invalid_scope');
235 });
236
237 test('wrong password re-renders the consent page; deny returns access_denied', async () =>
238 {
239 const { r } = await authorize('alice', 'wrong');
240 expect(r.status).toBe(401);
241 expect(r.text).toContain('Invalid username or password');
242
243 const { params } = await authorize('alice', 'x');
244 const d = await req('POST', '/oauth/authorize', { form: { ...params, decision: 'deny' } });
245 const loc = new URL(d.headers.get('location'));
246 expect(loc.searchParams.get('error')).toBe('access_denied');
247 expect(loc.searchParams.get('state')).toBe('st-1');
248 });
249
250 test('repeated failures are rate limited', async () =>
251 {
252 for (let i = 0; i < 10; i++) await authorize('alice', 'wrong');
253 const { r } = await authorize('alice', 'pw-alice');
254 expect(r.status).toBe(401);
255 expect(r.text).toContain('Too many failed attempts');
256 });
257
258 test('code exchange needs the right verifier and works only once', async () =>
259 {
260 const { r, verifier } = await authorize('alice', 'pw-alice');
261 const loc = new URL(r.headers.get('location'));
262 expect(loc.searchParams.get('state')).toBe('st-1');
263 expect(loc.searchParams.get('iss')).toBe(base);
264 const code = loc.searchParams.get('code');
265
266 const bad = await req('POST', '/oauth/token', { form: { grant_type: 'authorization_code', client_id: client.clientId, code, redirect_uri: REDIRECT, code_verifier: 'x'.repeat(43) } });
267 expect(bad.status).toBe(400);
268 // The failed attempt burned the code.
269 const again = await req('POST', '/oauth/token', { form: { grant_type: 'authorization_code', client_id: client.clientId, code, redirect_uri: REDIRECT, code_verifier: verifier } });
270 expect(again.data.error).toBe('invalid_grant');
271 });
272
273 test('loopback redirect accepts any port (RFC 8252)', async () =>
274 {
275 const { r } = await authorize('alice', 'pw-alice', 'files:read', { redirect_uri: 'http://127.0.0.1:53111/cb' });
276 expect(r.status).toBe(302);
277 expect(r.headers.get('location')).toMatch(/^http:\/\/127\.0\.0\.1:53111\/cb\?code=/);
278 });
279
280 test('tokens are stored hashed only', async () =>
281 {
282 const t = await login('alice');
283 const d = getDb();
284 const dump = JSON.stringify([
285 d.prepare('SELECT * FROM api_grants').all(),
286 d.prepare('SELECT * FROM api_access_tokens').all(),
287 ]);
288 expect(dump).not.toContain(t.access_token);
289 expect(dump).not.toContain(t.refresh_token);
290 expect(dump).toContain(store.sha256Hex(t.access_token));
291 });
292
293 test('refresh rotates tokens and reuse of an old refresh token revokes the grant', async () =>
294 {
295 const t1 = await login('alice');
296 const r2 = await req('POST', '/oauth/token', { form: { grant_type: 'refresh_token', client_id: client.clientId, refresh_token: t1.refresh_token } });
297 expect(r2.status).toBe(200);
298 expect(r2.data.refresh_token).not.toBe(t1.refresh_token);
299 expect((await req('GET', '/api/v1/me', { token: r2.data.access_token })).status).toBe(200);
300
301 const reuse = await req('POST', '/oauth/token', { form: { grant_type: 'refresh_token', client_id: client.clientId, refresh_token: t1.refresh_token } });
302 expect(reuse.status).toBe(400);
303 expect((await req('GET', '/api/v1/me', { token: r2.data.access_token })).status).toBe(401);
304 const r3 = await req('POST', '/oauth/token', { form: { grant_type: 'refresh_token', client_id: client.clientId, refresh_token: r2.data.refresh_token } });
305 expect(r3.status).toBe(400);
306 });
307
308 test('refresh token is bound to its client', async () =>
309 {
310 const other = store.createClient({ name: 'Other', redirectUris: [REDIRECT], createdBy: 'root' });
311 const t = await login('alice');
312 const r = await req('POST', '/oauth/token', { form: { grant_type: 'refresh_token', client_id: other.clientId, refresh_token: t.refresh_token } });
313 expect(r.status).toBe(400);
314 });
315
316 test('revocation endpoint kills the grant', async () =>
317 {
318 const t = await login('alice');
319 expect((await req('POST', '/oauth/revoke', { form: { token: t.refresh_token } })).status).toBe(200);
320 expect((await req('GET', '/api/v1/me', { token: t.access_token })).status).toBe(401);
321 });
322
323 test('disabling a client invalidates its tokens', async () =>
324 {
325 const c = store.createClient({ name: 'Temp', redirectUris: [REDIRECT], createdBy: 'root' });
326 const saved = client;
327 client = c;
328 const t = await login('alice');
329 client = saved;
330 expect((await req('GET', '/api/v1/me', { token: t.access_token })).status).toBe(200);
331 store.deleteClient(c.clientId);
332 expect((await req('GET', '/api/v1/me', { token: t.access_token })).status).toBe(401);
333 });
334 });
335
336 describe('Access management (web session)', () =>
337 {
338 test('user sees own grants only and can revoke them', async () =>
339 {
340 const a = await login('alice');
341 await login('bob');
342 const list = await req('GET', '/api/account/api-access/grants', { headers: { 'x-test-user': 'alice' } });
343 expect(list.data.grants.length).toBeGreaterThan(0);
344 const mine = list.data.grants.find((g) => g.id === a.grant_id);
345 expect(mine.name).toBe('Test phone');
346 expect(mine.clientName).toBe('Sync App');
347
348 const bobList = await req('GET', '/api/account/api-access/grants', { headers: { 'x-test-user': 'bob' } });
349 expect(bobList.data.grants.some((g) => g.id === a.grant_id)).toBe(false);
350 expect((await req('DELETE', `/api/account/api-access/grants/${a.grant_id}`, { headers: { 'x-test-user': 'bob' } })).status).toBe(404);
351
352 expect((await req('DELETE', `/api/account/api-access/grants/${a.grant_id}`, { headers: { 'x-test-user': 'alice' } })).status).toBe(200);
353 expect((await req('GET', '/api/v1/me', { token: a.access_token })).status).toBe(401);
354 });
355
356 test('personal access tokens work and can be revoked', async () =>
357 {
358 const r = await req('POST', '/api/account/api-access/tokens', { headers: { 'x-test-user': 'alice' }, json: { name: 'script', scopes: 'files:read' } });
359 expect(r.status).toBe(201);
360 expect(r.data.token).toMatch(/^fmp_/);
361 const me = await req('GET', '/api/v1/me', { token: r.data.token });
362 expect(me.data.username).toBe('alice');
363 expect(me.data.scopes).toEqual(['files:read']);
364 await req('DELETE', `/api/account/api-access/grants/${r.data.id}`, { headers: { 'x-test-user': 'alice' } });
365 expect((await req('GET', '/api/v1/me', { token: r.data.token })).status).toBe(401);
366 });
367
368 test('only admins manage clients and redirect URIs are validated', async () =>
369 {
370 expect((await req('POST', '/api/account/api-access/clients', { headers: { 'x-test-user': 'alice' }, json: { name: 'x', redirectUris: [REDIRECT] } })).status).toBe(403);
371 expect((await req('POST', '/api/account/api-access/clients', { headers: { 'x-test-user': 'root' }, json: { name: 'x', redirectUris: ['http://evil.example/cb'] } })).status).toBe(400);
372 const ok = await req('POST', '/api/account/api-access/clients', { headers: { 'x-test-user': 'root' }, json: { name: 'Desktop', redirectUris: ['com.example.sync:/cb', 'http://127.0.0.1/cb'] } });
373 expect(ok.status).toBe(201);
374 expect(ok.data.client.clientId).toMatch(/^fmc_/);
375 });
376 });
377
378 describe('Scopes and isolation', () =>
379 {
380 let alice;
381 let aliceRead;
382 let bob;
383
384 beforeAll(async () =>
385 {
386 alice = await login('alice');
387 aliceRead = await login('alice', 'files:read');
388 bob = await login('bob');
389 });
390
391 test('missing or bogus token is rejected', async () =>
392 {
393 expect((await req('GET', '/api/v1/roots')).status).toBe(401);
394 expect((await req('GET', '/api/v1/roots', { token: 'fma_nope' })).status).toBe(401);
395 });
396
397 test('roots reflect the user permissions', async () =>
398 {
399 const a = await req('GET', '/api/v1/roots', { token: alice.access_token });
400 expect(a.data.roots.map((r) => r.id)).toEqual(['~', 'shared', 'team']);
401 expect(a.data.roots.find((r) => r.id === 'shared').writable).toBe(false);
402 const b = await req('GET', '/api/v1/roots', { token: bob.access_token });
403 expect(b.data.roots.map((r) => r.id)).toEqual(['~', 'team']);
404 });
405
406 test('read-only token cannot write', async () =>
407 {
408 const r = await req('PUT', `/api/v1/files/content?path=${vq('/~/x.txt')}`, { token: aliceRead.access_token, body: 'x' });
409 expect(r.status).toBe(403);
410 expect(r.data.error).toBe('insufficient_scope');
411 });
412
413 test('cannot read roots without permission, other users folders, or escape via .. or symlinks', async () =>
414 {
415 expect((await req('GET', `/api/v1/files/content?path=${vq('/secret/secret.txt')}`, { token: alice.access_token })).status).toBe(404);
416 fs.mkdirSync(path.join(USERS_DIR, 'bob'), { recursive: true });
417 fs.writeFileSync(path.join(USERS_DIR, 'bob', 'private.txt'), 'bob only');
418 const viaHome = await req('GET', `/api/v1/files/content?path=${vq('/~/private.txt')}`, { token: alice.access_token });
419 expect(viaHome.status).toBe(404);
420 expect((await req('GET', `/api/v1/files/content?path=${vq('/~/../bob/private.txt')}`, { token: alice.access_token })).status).toBe(400);
421 expect((await req('GET', `/api/v1/files/content?path=${vq('/~/private.txt')}`, { token: bob.access_token })).text).toBe('bob only');
422
423 fs.mkdirSync(path.join(USERS_DIR, 'alice'), { recursive: true });
424 fs.symlinkSync(ROOTS.secret, path.join(USERS_DIR, 'alice', 'link'));
425 expect((await req('GET', `/api/v1/files/content?path=${vq('/~/link/secret.txt')}`, { token: alice.access_token })).status).toBe(404);
426 const list = await req('GET', `/api/v1/files/list?path=${vq('/~')}`, { token: alice.access_token });
427 expect(list.data.entries.some((e) => e.name === 'link')).toBe(false);
428 fs.unlinkSync(path.join(USERS_DIR, 'alice', 'link'));
429 });
430
431 test('read-only roots cannot be written even with files:write', async () =>
432 {
433 const r = await req('PUT', `/api/v1/files/content?path=${vq('/shared/new.txt')}`, { token: alice.access_token, body: 'x' });
434 expect(r.status).toBe(403);
435 expect(fs.existsSync(path.join(ROOTS.shared, 'new.txt'))).toBe(false);
436 const b = await req('POST', '/api/v1/folders', { token: bob.access_token, json: { path: '/team/x' } });
437 expect(b.status).toBe(403);
438 });
439
440 test('admin users get admin-level access, nothing more', async () =>
441 {
442 const root = await login('root');
443 const r = await req('GET', '/api/v1/roots', { token: root.access_token });
444 expect(r.data.roots.map((x) => x.id)).toEqual(['~', 'shared', 'team', 'secret']);
445 });
446 });
447
448 describe('Files: upload, download, conflicts', () =>
449 {
450 let t;
451 beforeAll(async () => { t = await login('alice'); });
452
453 test('simple upload, conditional overwrite and conflicts', async () =>
454 {
455 const mtime = Date.parse('2024-01-02T03:04:05.000Z');
456 const up = await req('PUT', `/api/v1/files/content?path=${vq('/team/a.txt')}&mtime=${mtime}`, { token: t.access_token, body: 'hello' });
457 expect(up.status).toBe(201);
458 expect(up.data).toMatchObject({ path: '/team/a.txt', type: 'file', size: 5, mtime_ms: mtime });
459 expect(up.data.sha256).toBe(crypto.createHash('sha256').update('hello').digest('hex'));
460 expect(fs.readFileSync(path.join(ROOTS.team, 'a.txt'), 'utf8')).toBe('hello');
461
462 const conflict = await req('PUT', `/api/v1/files/content?path=${vq('/team/a.txt')}`, { token: t.access_token, body: 'x' });
463 expect(conflict.status).toBe(409);
464 expect(conflict.data.current.version).toBe(up.data.version);
465
466 const noneMatch = await req('PUT', `/api/v1/files/content?path=${vq('/team/a.txt')}`, { token: t.access_token, body: 'x', headers: { 'If-None-Match': '*' } });
467 expect(noneMatch.status).toBe(412);
468
469 const stale = await req('PUT', `/api/v1/files/content?path=${vq('/team/a.txt')}`, { token: t.access_token, body: 'x', headers: { 'If-Match': '"stale"' } });
470 expect(stale.status).toBe(412);
471
472 const ok = await req('PUT', `/api/v1/files/content?path=${vq('/team/a.txt')}`, { token: t.access_token, body: 'hello world', headers: { 'If-Match': `"${up.data.version}"` } });
473 expect(ok.status).toBe(200);
474 expect(ok.data.version).not.toBe(up.data.version);
475 expect(ok.headers.get('etag')).toBe(`"${ok.data.version}"`);
476
477 const forced = await req('PUT', `/api/v1/files/content?path=${vq('/team/a.txt')}&overwrite=true`, { token: t.access_token, body: 'hello world!' });
478 expect(forced.status).toBe(200);
479 });
480
481 test('upload into a missing folder fails cleanly and leaves no temp files', async () =>
482 {
483 const r = await req('PUT', `/api/v1/files/content?path=${vq('/team/nope/a.txt')}`, { token: t.access_token, body: 'x' });
484 expect(r.status).toBe(409);
485 expect(r.data.error).toBe('parent_missing');
486 expect(fs.readdirSync(ROOTS.team).some((n) => n.startsWith('.fmapi-'))).toBe(false);
487 });
488
489 test('checksum mismatch is refused', async () =>
490 {
491 const r = await req('PUT', `/api/v1/files/content?path=${vq('/team/sum.txt')}`, { token: t.access_token, body: 'abc', headers: { 'X-Content-SHA256': '0'.repeat(64) } });
492 expect(r.status).toBe(422);
493 expect(fs.existsSync(path.join(ROOTS.team, 'sum.txt'))).toBe(false);
494 });
495
496 test('download supports ETag, 304 and Range', async () =>
497 {
498 const meta = await req('GET', `/api/v1/files/metadata?path=${vq('/team/a.txt')}`, { token: t.access_token });
499 const full = await req('GET', `/api/v1/files/content?path=${vq('/team/a.txt')}`, { token: t.access_token });
500 expect(full.status).toBe(200);
501 expect(full.text).toBe('hello world!');
502 expect(full.headers.get('etag')).toBe(`"${meta.data.version}"`);
503
504 const cached = await req('GET', `/api/v1/files/content?path=${vq('/team/a.txt')}`, { token: t.access_token, headers: { 'If-None-Match': `"${meta.data.version}"` } });
505 expect(cached.status).toBe(304);
506
507 const part = await req('GET', `/api/v1/files/content?path=${vq('/team/a.txt')}`, { token: t.access_token, headers: { Range: 'bytes=6-10' } });
508 expect(part.status).toBe(206);
509 expect(part.text).toBe('world');
510 expect(part.headers.get('content-range')).toBe('bytes 6-10/12');
511 });
512
513 test('metadata can compute a hash on demand for files changed outside the API', async () =>
514 {
515 fs.writeFileSync(path.join(ROOTS.team, 'outside.bin'), 'outside');
516 const m1 = await req('GET', `/api/v1/files/metadata?path=${vq('/team/outside.bin')}`, { token: t.access_token });
517 expect(m1.data.sha256).toBeNull();
518 const m2 = await req('GET', `/api/v1/files/metadata?path=${vq('/team/outside.bin')}&hash=1`, { token: t.access_token });
519 expect(m2.data.sha256).toBe(crypto.createHash('sha256').update('outside').digest('hex'));
520 });
521
522 test('folders, listing, move and delete', async () =>
523 {
524 expect((await req('POST', '/api/v1/folders', { token: t.access_token, json: { path: '/team/docs/sub', parents: true } })).status).toBe(201);
525 expect((await req('POST', '/api/v1/folders', { token: t.access_token, json: { path: '/team/docs' } })).status).toBe(409);
526 expect((await req('POST', '/api/v1/folders', { token: t.access_token, json: { path: '/team/docs', exist_ok: true } })).status).toBe(200);
527 await req('PUT', `/api/v1/files/content?path=${vq('/team/docs/b.txt')}`, { token: t.access_token, body: 'b' });
528
529 const list = await req('GET', `/api/v1/files/list?path=${vq('/team/docs')}&limit=1`, { token: t.access_token });
530 expect(list.data.entries).toHaveLength(1);
531 expect(list.data.next_page_token).toBe('1');
532
533 const mv = await req('POST', '/api/v1/files/move', { token: t.access_token, json: { from: '/team/docs/b.txt', to: '/team/docs/sub/c.txt' } });
534 expect(mv.status).toBe(200);
535 expect(mv.data.path).toBe('/team/docs/sub/c.txt');
536
537 await req('PUT', `/api/v1/files/content?path=${vq('/team/docs/d.txt')}`, { token: t.access_token, body: 'd' });
538 const clash = await req('POST', '/api/v1/files/move', { token: t.access_token, json: { from: '/team/docs/d.txt', to: '/team/docs/sub/c.txt' } });
539 expect(clash.status).toBe(409);
540 const into = await req('POST', '/api/v1/files/move', { token: t.access_token, json: { from: '/team/docs', to: '/team/docs/sub/x' } });
541 expect(into.status).toBe(400);
542 const toReadOnly = await req('POST', '/api/v1/files/move', { token: t.access_token, json: { from: '/team/docs/d.txt', to: '/shared/d.txt' } });
543 expect(toReadOnly.status).toBe(403);
544
545 expect((await req('DELETE', `/api/v1/files?path=${vq('/team/docs')}`, { token: t.access_token })).status).toBe(409);
546 expect((await req('DELETE', `/api/v1/files?path=${vq('/team/docs/d.txt')}`, { token: t.access_token, headers: { 'If-Match': '"old"' } })).status).toBe(412);
547 expect((await req('DELETE', `/api/v1/files?path=${vq('/team/docs')}&recursive=true`, { token: t.access_token })).status).toBe(204);
548 expect(fs.existsSync(path.join(ROOTS.team, 'docs'))).toBe(false);
549 expect((await req('DELETE', `/api/v1/files?path=${vq('/team')}`, { token: t.access_token })).status).toBe(400);
550 });
551
552 test('errors are JSON, also for unknown endpoints', async () =>
553 {
554 const r = await req('GET', '/api/v1/nope', { token: t.access_token });
555 expect(r.status).toBe(404);
556 expect(r.data.error).toBe('not_found');
557 const bad = await req('GET', '/api/v1/files/metadata?path=relative', { token: t.access_token });
558 expect(bad.data.error).toBe('invalid_path');
559 });
560 });
561
562 describe('Resumable uploads', () =>
563 {
564 let t;
565 let other;
566 beforeAll(async () => { t = await login('alice'); other = await login('alice'); });
567
568 test('chunked upload with offsets, resume info and checksum', async () =>
569 {
570 const content = crypto.randomBytes(2.5 * 1024 * 1024);
571 const sha = crypto.createHash('sha256').update(content).digest('hex');
572 const c = await req('POST', '/api/v1/uploads', { token: t.access_token, json: { path: '/team/big.bin', size: content.length, sha256: sha, mtime: 1700000000000 } });
573 expect(c.status).toBe(201);
574 const id = c.data.id;
575 expect(c.data.max_chunk_bytes).toBe(1024 * 1024);
576
577 // Another grant (even of the same user) cannot touch this session.
578 expect((await req('GET', `/api/v1/uploads/${id}`, { token: other.access_token })).status).toBe(404);
579
580 const tooBig = await req('PATCH', `/api/v1/uploads/${id}`, { token: t.access_token, headers: { 'Upload-Offset': '0' }, body: content.subarray(0, 1024 * 1024 + 1) });
581 expect(tooBig.status).toBe(413);
582 expect((await req('GET', `/api/v1/uploads/${id}`, { token: t.access_token })).data.offset).toBe(0);
583
584 let offset = 0;
585 while (offset < content.length)
586 {
587 const chunk = content.subarray(offset, offset + 1024 * 1024);
588 const p = await req('PATCH', `/api/v1/uploads/${id}`, { token: t.access_token, headers: { 'Upload-Offset': String(offset) }, body: chunk });
589 expect(p.status).toBe(200);
590 offset = p.data.offset;
591 if (offset === 1024 * 1024)
592 {
593 const wrong = await req('PATCH', `/api/v1/uploads/${id}`, { token: t.access_token, headers: { 'Upload-Offset': '0' }, body: 'x' });
594 expect(wrong.status).toBe(409);
595 expect(wrong.data.offset).toBe(1024 * 1024);
596 const early = await req('POST', `/api/v1/uploads/${id}/complete`, { token: t.access_token });
597 expect(early.status).toBe(409);
598 }
599 }
600 const done = await req('POST', `/api/v1/uploads/${id}/complete`, { token: t.access_token });
601 expect(done.status).toBe(201);
602 expect(done.data).toMatchObject({ path: '/team/big.bin', size: content.length, sha256: sha, mtime_ms: 1700000000000 });
603 expect(fs.readFileSync(path.join(ROOTS.team, 'big.bin')).equals(content)).toBe(true);
604 expect(fs.readdirSync(mockConfig.api.uploadDir)).toEqual([]);
605 });
606
607 test('checksum mismatch discards the upload', async () =>
608 {
609 const c = await req('POST', '/api/v1/uploads', { token: t.access_token, json: { path: '/team/bad.bin', size: 3, sha256: '0'.repeat(64) } });
610 await req('PATCH', `/api/v1/uploads/${c.data.id}`, { token: t.access_token, headers: { 'Upload-Offset': '0' }, body: 'abc' });
611 const r = await req('POST', `/api/v1/uploads/${c.data.id}/complete`, { token: t.access_token });
612 expect(r.status).toBe(422);
613 expect(fs.existsSync(path.join(ROOTS.team, 'bad.bin'))).toBe(false);
614 });
615
616 test('preconditions are checked at start and at completion', async () =>
617 {
618 const exists = await req('POST', '/api/v1/uploads', { token: t.access_token, json: { path: '/team/big.bin', size: 1 } });
619 expect(exists.status).toBe(409);
620 const c = await req('POST', '/api/v1/uploads', { token: t.access_token, json: { path: '/team/race.txt', size: 1, if_none_match: '*' } });
621 await req('PATCH', `/api/v1/uploads/${c.data.id}`, { token: t.access_token, headers: { 'Upload-Offset': '0' }, body: 'z' });
622 fs.writeFileSync(path.join(ROOTS.team, 'race.txt'), 'someone else');
623 const r = await req('POST', `/api/v1/uploads/${c.data.id}/complete`, { token: t.access_token });
624 expect(r.status).toBe(412);
625 expect(fs.readFileSync(path.join(ROOTS.team, 'race.txt'), 'utf8')).toBe('someone else');
626 });
627
628 test('cancel removes the staged data', async () =>
629 {
630 const c = await req('POST', '/api/v1/uploads', { token: t.access_token, json: { path: '/team/cancel.bin', size: 10 } });
631 expect((await req('DELETE', `/api/v1/uploads/${c.data.id}`, { token: t.access_token })).status).toBe(204);
632 expect((await req('GET', `/api/v1/uploads/${c.data.id}`, { token: t.access_token })).status).toBe(404);
633 });
634 });
635
636 describe('Delta feed', () =>
637 {
638 let t;
639 let bob;
640 beforeAll(async () => { t = await login('alice'); bob = await login('bob'); });
641
642 async function drain (cursor)
643 {
644 const all = [];
645 let c = cursor;
646 for (;;)
647 {
648 const r = await req('GET', `/api/v1/delta?root=${vq('~')}&cursor=${c}&limit=2`, { token: t.access_token });
649 expect(r.status).toBe(200);
650 all.push(...r.data.entries);
651 c = r.data.cursor;
652 if (!r.data.has_more) return { entries: all, cursor: c };
653 }
654 }
655
656 test('snapshot, then created/modified/moved/deleted incl. changes made outside the API', async () =>
657 {
658 const home = path.join(USERS_DIR, 'alice');
659 fs.mkdirSync(path.join(home, 'photos'), { recursive: true });
660 fs.writeFileSync(path.join(home, 'photos', '1.jpg'), 'one');
661 fs.writeFileSync(path.join(home, 'notes.txt'), 'n');
662
663 // Initial snapshot, paged.
664 let r = await req('GET', `/api/v1/delta?root=${vq('~')}&limit=2`, { token: t.access_token });
665 expect(r.data.reset).toBe(true);
666 const snap = [...r.data.entries];
667 let cursor = r.data.cursor;
668 while (r.data.has_more)
669 {
670 r = await req('GET', `/api/v1/delta?root=${vq('~')}&cursor=${cursor}&limit=2`, { token: t.access_token });
671 snap.push(...r.data.entries);
672 cursor = r.data.cursor;
673 }
674 expect(snap.map((e) => e.path).sort()).toEqual(expect.arrayContaining(['/~/notes.txt', '/~/photos', '/~/photos/1.jpg']));
675 expect(snap.every((e) => e.change === 'exists')).toBe(true);
676
677 // No changes.
678 let d = await drain(cursor);
679 expect(d.entries).toEqual([]);
680 cursor = d.cursor;
681
682 // Changes through the API.
683 await req('PUT', `/api/v1/files/content?path=${vq('/~/new.txt')}`, { token: t.access_token, body: 'new' });
684 await req('POST', '/api/v1/files/move', { token: t.access_token, json: { from: '/~/photos', to: '/~/pictures' } });
685 d = await drain(cursor);
686 cursor = d.cursor;
687 expect(d.entries).toEqual(expect.arrayContaining([
688 expect.objectContaining({ change: 'created', path: '/~/new.txt', type: 'file', size: 3 }),
689 expect.objectContaining({ change: 'moved', path: '/~/pictures', old_path: '/~/photos', type: 'folder' }),
690 ]));
691 // Children of a moved folder are implied, not repeated.
692 expect(d.entries.some((e) => e.path === '/~/pictures/1.jpg')).toBe(false);
693
694 // Changes made directly on disk / via the web UI.
695 await new Promise((res) => setTimeout(res, 20));
696 fs.writeFileSync(path.join(home, 'notes.txt'), 'changed notes');
697 fs.rmSync(path.join(home, 'pictures'), { recursive: true });
698 d = await drain(cursor);
699 cursor = d.cursor;
700 expect(d.entries).toEqual(expect.arrayContaining([
701 expect.objectContaining({ change: 'modified', path: '/~/notes.txt', size: 13 }),
702 expect.objectContaining({ change: 'deleted', path: '/~/pictures', type: 'folder' }),
703 ]));
704 expect(d.entries.some((e) => e.path === '/~/pictures/1.jpg')).toBe(false);
705 const del = d.entries.find((e) => e.change === 'deleted');
706 expect(del.version).toBeNull();
707 });
708
709 test('cursor is bound to its root and unknown roots are hidden', async () =>
710 {
711 const r = await req('GET', `/api/v1/delta?root=${vq('~')}`, { token: t.access_token });
712 const other = await req('GET', `/api/v1/delta?root=team&cursor=${r.data.cursor}`, { token: t.access_token });
713 expect(other.status).toBe(400);
714 expect((await req('GET', '/api/v1/delta?root=secret', { token: t.access_token })).status).toBe(404);
715 expect((await req('GET', '/api/v1/delta?root=x&cursor=%%%', { token: t.access_token })).status).toBe(400);
716 });
717
718 test('another user sees their own home, not alice\'s', async () =>
719 {
720 const r = await req('GET', `/api/v1/delta?root=${vq('~')}&limit=1000`, { token: bob.access_token });
721 expect(r.data.entries.map((e) => e.path)).toEqual(['/~/private.txt']);
722 });
723
724 test('pruned history answers 410 so clients start over', async () =>
725 {
726 const r = await req('GET', '/api/v1/delta?root=team&limit=1000', { token: t.access_token });
727 expect(r.data.has_more).toBe(false);
728 getDb().prepare('UPDATE api_scan_state SET min_seq = min_seq + 100000 WHERE root_key = ?').run([ROOTS.team]);
729 const gone = await req('GET', `/api/v1/delta?root=team&cursor=${r.data.cursor}`, { token: t.access_token });
730 expect(gone.status).toBe(410);
731 expect(gone.data.error).toBe('cursor_expired');
732 });
733 });
@@ -0,0 +1,733 @@
1'use strict';
2
3// Public sync API + OAuth: auth flow, scopes, isolation between users,
4// uploads/downloads, delta feed and conflict detection.
5
6const fs = require('fs');
7const os = require('os');
8const path = require('path');
9const http = require('http');
10const crypto = require('crypto');
11const express = require('express');
12const bcrypt = require('bcrypt');
13const { once } = require('events');
14
15const mockBase = fs.mkdtempSync(path.join(os.tmpdir(), 'fm-api-'));
16const mockConfig = {
17 port: 3000,
18 paths: [],
19 userPath: null,
20 rootAliases: {},
21 api: { scanIntervalSeconds: 0.001, maxChunkBytes: 1024 * 1024, uploadDir: null },
22};
23
24jest.mock('../server/db', () =>
25{
26 const { Database } = require('node-sqlite3-wasm');
27 let db;
28 function getDb ()
29 {
30 if (!db)
31 {
32 db = new Database(':memory:');
33 db.exec(`
34 CREATE TABLE users (id INTEGER PRIMARY KEY AUTOINCREMENT, username TEXT UNIQUE NOT NULL, password_hash TEXT NOT NULL,
35 is_admin INTEGER NOT NULL DEFAULT 0, permissions TEXT NOT NULL DEFAULT '{}');
36 CREATE TABLE file_meta (file_path TEXT PRIMARY KEY, uploader TEXT NOT NULL DEFAULT '', downloaders TEXT NOT NULL DEFAULT '[]',
37 watched_by TEXT NOT NULL DEFAULT '{}', uploaded_at TEXT, sha256 TEXT);
38 CREATE TABLE user_last_navigation (username TEXT PRIMARY KEY, last_dir TEXT, updated_at INTEGER NOT NULL);
39 `);
40 }
41 return db;
42 }
43 return { getDb, initDb: () => {}, closeDb: () => {} };
44});
45
46jest.mock('../server/config', () =>
47{
48 const actual = jest.requireActual('../server/config');
49 return { ...actual, loadConfig: () => mockConfig, saveConfig: () => {} };
50});
51
52jest.mock('../server/auth', () =>
53{
54 const actual = jest.requireActual('../server/auth');
55 return {
56 ...actual,
57 // Web-session auth stand-in for the management routes.
58 requireAuth: (req, res, next) =>
59 {
60 const name = req.get('x-test-user');
61 const { getDb } = require('../server/db');
62 const row = name ? getDb().prepare('SELECT * FROM users WHERE username = ?').get([name]) : null;
63 if (!row) return res.status(401).json({ error: 'Session invalid or expired.' });
64 req.user = { id: row.id, username: row.username, isAdmin: row.is_admin === 1, permissions: JSON.parse(row.permissions) };
65 next();
66 },
67 };
68});
69
70jest.mock('../server/search-index', () => ({
71 searchFiles: async () => [],
72 deleteIndexPath: () => {},
73 deleteIndexUnder: () => {},
74 rewriteIndexPaths: () => {},
75 reindexDirectoryTree: async () => {},
76}));
77jest.mock('../server/file-hash-queue', () => ({ enqueueFileHash: () => {} }));
78jest.mock('../server/thumbnail-cache', () => ({
79 getCachedThumbnailInfo: async () => null,
80 getFilesWithThumbnailsInDir: async () => [],
81 getFolderIconSourceFile: async () => null,
82 setFolderIconAssignment: () => {},
83 getThumbnailManifestSourcePathSet: async () => new Set(),
84 needsPreviewImageConversion: () => false,
85 streamPreviewImage: async () => {},
86 MAX_PREVIEW_IMAGE_BYTES: 1,
87 THUMB_HTTP_MAX_AGE_SEC: 1,
88}));
89
90const { getDb } = require('../server/db');
91const store = require('../server/api/store');
92const oauthRoutes = require('../server/api/oauth');
93const apiV1Routes = require('../server/api/v1');
94const manageRoutes = require('../server/api/manage');
95
96const ROOTS = {
97 shared: path.join(mockBase, 'roots', 'shared'),
98 team: path.join(mockBase, 'roots', 'team'),
99 secret: path.join(mockBase, 'roots', 'secret'),
100};
101const USERS_DIR = path.join(mockBase, 'users');
102const REDIRECT = 'https://sync.example.com/callback';
103
104let server;
105let base;
106let client;
107
108function verifierPair ()
109{
110 const verifier = crypto.randomBytes(32).toString('base64url');
111 return { verifier, challenge: crypto.createHash('sha256').update(verifier).digest('base64url') };
112}
113
114async function req (method, url, { token, headers = {}, body, form, json, redirect = 'manual' } = {})
115{
116 const h = { ...headers };
117 if (token) h.Authorization = `Bearer ${token}`;
118 let payload = body;
119 if (form) { h['Content-Type'] = 'application/x-www-form-urlencoded'; payload = new URLSearchParams(form).toString(); }
120 if (json !== undefined) { h['Content-Type'] = 'application/json'; payload = JSON.stringify(json); }
121 const res = await fetch(base + url, { method, headers: h, body: payload, redirect });
122 const buf = Buffer.from(await res.arrayBuffer());
123 let data = null;
124 if ((res.headers.get('content-type') || '').includes('json') && buf.length) data = JSON.parse(buf.toString('utf8'));
125 return { status: res.status, headers: res.headers, data, buf, text: buf.toString('utf8') };
126}
127
128async function authorize (username, password, scope = 'files:read files:write', extra = {})
129{
130 const { verifier, challenge } = verifierPair();
131 const params = {
132 response_type: 'code', client_id: client.clientId, redirect_uri: REDIRECT, scope, state: 'st-1',
133 code_challenge: challenge, code_challenge_method: 'S256', device_name: 'Test phone', ...extra,
134 };
135 const r = await req('POST', '/oauth/authorize', { form: { ...params, username, password, decision: 'allow' } });
136 return { r, verifier, params };
137}
138
139async function login (username, scope)
140{
141 const { r, verifier } = await authorize(username, 'pw-' + username, scope);
142 expect(r.status).toBe(302);
143 const code = new URL(r.headers.get('location')).searchParams.get('code');
144 const t = await req('POST', '/oauth/token', { form: { grant_type: 'authorization_code', client_id: client.clientId, code, redirect_uri: REDIRECT, code_verifier: verifier } });
145 expect(t.status).toBe(200);
146 return t.data;
147}
148
149function vq (p) { return encodeURIComponent(p); }
150
151beforeAll(async () =>
152{
153 for (const r of Object.values(ROOTS)) fs.mkdirSync(r, { recursive: true });
154 fs.mkdirSync(USERS_DIR, { recursive: true });
155 fs.writeFileSync(path.join(ROOTS.secret, 'secret.txt'), 'top secret');
156 fs.writeFileSync(path.join(ROOTS.shared, 'readme.txt'), 'shared readme');
157 mockConfig.paths = Object.values(ROOTS);
158 mockConfig.userPath = USERS_DIR;
159 mockConfig.api.uploadDir = path.join(mockBase, 'staging');
160
161 const d = getDb();
162 store.initApiSchema(d);
163 const hash = (pw) => bcrypt.hashSync(pw, 4);
164 d.prepare('INSERT INTO users (username, password_hash, is_admin, permissions) VALUES (?, ?, ?, ?)')
165 .run(['alice', hash('pw-alice'), 0, JSON.stringify({ shared: { read: true, write: false }, team: { read: true, write: true } })]);
166 d.prepare('INSERT INTO users (username, password_hash, is_admin, permissions) VALUES (?, ?, ?, ?)')
167 .run(['bob', hash('pw-bob'), 0, JSON.stringify({ team: { read: true, write: false } })]);
168 d.prepare('INSERT INTO users (username, password_hash, is_admin, permissions) VALUES (?, ?, ?, ?)')
169 .run(['root', hash('pw-root'), 1, '{}']);
170
171 const app = express();
172 app.use(oauthRoutes);
173 app.use('/api/v1', apiV1Routes);
174 app.use(express.json());
175 app.use('/api/account/api-access', manageRoutes);
176 server = http.createServer(app).listen(0, '127.0.0.1');
177 await once(server, 'listening');
178 base = `http://127.0.0.1:${server.address().port}`;
179 client = store.createClient({ name: 'Sync App', redirectUris: [REDIRECT, 'http://127.0.0.1/cb'], createdBy: 'root' });
180});
181
182afterAll(async () =>
183{
184 server.close();
185 fs.rmSync(mockBase, { recursive: true, force: true });
186});
187
188beforeEach(() => oauthRoutes.resetLoginFailures());
189
190// ---------------------------------------------------------------------------
191
192describe('OAuth authorization code + PKCE', () =>
193{
194 test('metadata advertises PKCE S256 and public clients', async () =>
195 {
196 const r = await req('GET', '/.well-known/oauth-authorization-server');
197 expect(r.data.code_challenge_methods_supported).toEqual(['S256']);
198 expect(r.data.token_endpoint_auth_methods_supported).toEqual(['none']);
199 });
200
201 test('consent page shows client, device and scopes and cannot be framed', async () =>
202 {
203 const { challenge } = verifierPair();
204 const q = new URLSearchParams({ response_type: 'code', client_id: client.clientId, redirect_uri: REDIRECT, scope: 'files:read', code_challenge: challenge, code_challenge_method: 'S256', device_name: 'Pixel <8>' });
205 const r = await req('GET', `/oauth/authorize?${q}`);
206 expect(r.status).toBe(200);
207 expect(r.text).toContain('Sync App');
208 expect(r.text).toContain('Pixel &lt;8&gt;');
209 expect(r.text).toContain('files:read');
210 expect(r.headers.get('x-frame-options')).toBe('DENY');
211 });
212
213 test('unknown client or unregistered redirect never redirects', async () =>
214 {
215 const { challenge } = verifierPair();
216 let r = await req('GET', `/oauth/authorize?response_type=code&client_id=nope&redirect_uri=${vq(REDIRECT)}&code_challenge=${challenge}&code_challenge_method=S256`);
217 expect(r.status).toBe(400);
218 r = await req('GET', `/oauth/authorize?response_type=code&client_id=${client.clientId}&redirect_uri=${vq('https://evil.example/cb')}&code_challenge=${challenge}&code_challenge_method=S256`);
219 expect(r.status).toBe(400);
220 });
221
222 test('PKCE is mandatory and only S256', async () =>
223 {
224 let r = await req('GET', `/oauth/authorize?response_type=code&client_id=${client.clientId}&redirect_uri=${vq(REDIRECT)}&state=x`);
225 expect(r.status).toBe(302);
226 expect(new URL(r.headers.get('location')).searchParams.get('error')).toBe('invalid_request');
227 r = await req('GET', `/oauth/authorize?response_type=code&client_id=${client.clientId}&redirect_uri=${vq(REDIRECT)}&code_challenge=${'a'.repeat(43)}&code_challenge_method=plain`);
228 expect(new URL(r.headers.get('location')).searchParams.get('error')).toBe('invalid_request');
229 });
230
231 test('unknown scopes are rejected', async () =>
232 {
233 const { r } = await authorize('alice', 'pw-alice', 'files:read admin');
234 expect(new URL(r.headers.get('location')).searchParams.get('error')).toBe('invalid_scope');
235 });
236
237 test('wrong password re-renders the consent page; deny returns access_denied', async () =>
238 {
239 const { r } = await authorize('alice', 'wrong');
240 expect(r.status).toBe(401);
241 expect(r.text).toContain('Invalid username or password');
242
243 const { params } = await authorize('alice', 'x');
244 const d = await req('POST', '/oauth/authorize', { form: { ...params, decision: 'deny' } });
245 const loc = new URL(d.headers.get('location'));
246 expect(loc.searchParams.get('error')).toBe('access_denied');
247 expect(loc.searchParams.get('state')).toBe('st-1');
248 });
249
250 test('repeated failures are rate limited', async () =>
251 {
252 for (let i = 0; i < 10; i++) await authorize('alice', 'wrong');
253 const { r } = await authorize('alice', 'pw-alice');
254 expect(r.status).toBe(401);
255 expect(r.text).toContain('Too many failed attempts');
256 });
257
258 test('code exchange needs the right verifier and works only once', async () =>
259 {
260 const { r, verifier } = await authorize('alice', 'pw-alice');
261 const loc = new URL(r.headers.get('location'));
262 expect(loc.searchParams.get('state')).toBe('st-1');
263 expect(loc.searchParams.get('iss')).toBe(base);
264 const code = loc.searchParams.get('code');
265
266 const bad = await req('POST', '/oauth/token', { form: { grant_type: 'authorization_code', client_id: client.clientId, code, redirect_uri: REDIRECT, code_verifier: 'x'.repeat(43) } });
267 expect(bad.status).toBe(400);
268 // The failed attempt burned the code.
269 const again = await req('POST', '/oauth/token', { form: { grant_type: 'authorization_code', client_id: client.clientId, code, redirect_uri: REDIRECT, code_verifier: verifier } });
270 expect(again.data.error).toBe('invalid_grant');
271 });
272
273 test('loopback redirect accepts any port (RFC 8252)', async () =>
274 {
275 const { r } = await authorize('alice', 'pw-alice', 'files:read', { redirect_uri: 'http://127.0.0.1:53111/cb' });
276 expect(r.status).toBe(302);
277 expect(r.headers.get('location')).toMatch(/^http:\/\/127\.0\.0\.1:53111\/cb\?code=/);
278 });
279
280 test('tokens are stored hashed only', async () =>
281 {
282 const t = await login('alice');
283 const d = getDb();
284 const dump = JSON.stringify([
285 d.prepare('SELECT * FROM api_grants').all(),
286 d.prepare('SELECT * FROM api_access_tokens').all(),
287 ]);
288 expect(dump).not.toContain(t.access_token);
289 expect(dump).not.toContain(t.refresh_token);
290 expect(dump).toContain(store.sha256Hex(t.access_token));
291 });
292
293 test('refresh rotates tokens and reuse of an old refresh token revokes the grant', async () =>
294 {
295 const t1 = await login('alice');
296 const r2 = await req('POST', '/oauth/token', { form: { grant_type: 'refresh_token', client_id: client.clientId, refresh_token: t1.refresh_token } });
297 expect(r2.status).toBe(200);
298 expect(r2.data.refresh_token).not.toBe(t1.refresh_token);
299 expect((await req('GET', '/api/v1/me', { token: r2.data.access_token })).status).toBe(200);
300
301 const reuse = await req('POST', '/oauth/token', { form: { grant_type: 'refresh_token', client_id: client.clientId, refresh_token: t1.refresh_token } });
302 expect(reuse.status).toBe(400);
303 expect((await req('GET', '/api/v1/me', { token: r2.data.access_token })).status).toBe(401);
304 const r3 = await req('POST', '/oauth/token', { form: { grant_type: 'refresh_token', client_id: client.clientId, refresh_token: r2.data.refresh_token } });
305 expect(r3.status).toBe(400);
306 });
307
308 test('refresh token is bound to its client', async () =>
309 {
310 const other = store.createClient({ name: 'Other', redirectUris: [REDIRECT], createdBy: 'root' });
311 const t = await login('alice');
312 const r = await req('POST', '/oauth/token', { form: { grant_type: 'refresh_token', client_id: other.clientId, refresh_token: t.refresh_token } });
313 expect(r.status).toBe(400);
314 });
315
316 test('revocation endpoint kills the grant', async () =>
317 {
318 const t = await login('alice');
319 expect((await req('POST', '/oauth/revoke', { form: { token: t.refresh_token } })).status).toBe(200);
320 expect((await req('GET', '/api/v1/me', { token: t.access_token })).status).toBe(401);
321 });
322
323 test('disabling a client invalidates its tokens', async () =>
324 {
325 const c = store.createClient({ name: 'Temp', redirectUris: [REDIRECT], createdBy: 'root' });
326 const saved = client;
327 client = c;
328 const t = await login('alice');
329 client = saved;
330 expect((await req('GET', '/api/v1/me', { token: t.access_token })).status).toBe(200);
331 store.deleteClient(c.clientId);
332 expect((await req('GET', '/api/v1/me', { token: t.access_token })).status).toBe(401);
333 });
334});
335
336describe('Access management (web session)', () =>
337{
338 test('user sees own grants only and can revoke them', async () =>
339 {
340 const a = await login('alice');
341 await login('bob');
342 const list = await req('GET', '/api/account/api-access/grants', { headers: { 'x-test-user': 'alice' } });
343 expect(list.data.grants.length).toBeGreaterThan(0);
344 const mine = list.data.grants.find((g) => g.id === a.grant_id);
345 expect(mine.name).toBe('Test phone');
346 expect(mine.clientName).toBe('Sync App');
347
348 const bobList = await req('GET', '/api/account/api-access/grants', { headers: { 'x-test-user': 'bob' } });
349 expect(bobList.data.grants.some((g) => g.id === a.grant_id)).toBe(false);
350 expect((await req('DELETE', `/api/account/api-access/grants/${a.grant_id}`, { headers: { 'x-test-user': 'bob' } })).status).toBe(404);
351
352 expect((await req('DELETE', `/api/account/api-access/grants/${a.grant_id}`, { headers: { 'x-test-user': 'alice' } })).status).toBe(200);
353 expect((await req('GET', '/api/v1/me', { token: a.access_token })).status).toBe(401);
354 });
355
356 test('personal access tokens work and can be revoked', async () =>
357 {
358 const r = await req('POST', '/api/account/api-access/tokens', { headers: { 'x-test-user': 'alice' }, json: { name: 'script', scopes: 'files:read' } });
359 expect(r.status).toBe(201);
360 expect(r.data.token).toMatch(/^fmp_/);
361 const me = await req('GET', '/api/v1/me', { token: r.data.token });
362 expect(me.data.username).toBe('alice');
363 expect(me.data.scopes).toEqual(['files:read']);
364 await req('DELETE', `/api/account/api-access/grants/${r.data.id}`, { headers: { 'x-test-user': 'alice' } });
365 expect((await req('GET', '/api/v1/me', { token: r.data.token })).status).toBe(401);
366 });
367
368 test('only admins manage clients and redirect URIs are validated', async () =>
369 {
370 expect((await req('POST', '/api/account/api-access/clients', { headers: { 'x-test-user': 'alice' }, json: { name: 'x', redirectUris: [REDIRECT] } })).status).toBe(403);
371 expect((await req('POST', '/api/account/api-access/clients', { headers: { 'x-test-user': 'root' }, json: { name: 'x', redirectUris: ['http://evil.example/cb'] } })).status).toBe(400);
372 const ok = await req('POST', '/api/account/api-access/clients', { headers: { 'x-test-user': 'root' }, json: { name: 'Desktop', redirectUris: ['com.example.sync:/cb', 'http://127.0.0.1/cb'] } });
373 expect(ok.status).toBe(201);
374 expect(ok.data.client.clientId).toMatch(/^fmc_/);
375 });
376});
377
378describe('Scopes and isolation', () =>
379{
380 let alice;
381 let aliceRead;
382 let bob;
383
384 beforeAll(async () =>
385 {
386 alice = await login('alice');
387 aliceRead = await login('alice', 'files:read');
388 bob = await login('bob');
389 });
390
391 test('missing or bogus token is rejected', async () =>
392 {
393 expect((await req('GET', '/api/v1/roots')).status).toBe(401);
394 expect((await req('GET', '/api/v1/roots', { token: 'fma_nope' })).status).toBe(401);
395 });
396
397 test('roots reflect the user permissions', async () =>
398 {
399 const a = await req('GET', '/api/v1/roots', { token: alice.access_token });
400 expect(a.data.roots.map((r) => r.id)).toEqual(['~', 'shared', 'team']);
401 expect(a.data.roots.find((r) => r.id === 'shared').writable).toBe(false);
402 const b = await req('GET', '/api/v1/roots', { token: bob.access_token });
403 expect(b.data.roots.map((r) => r.id)).toEqual(['~', 'team']);
404 });
405
406 test('read-only token cannot write', async () =>
407 {
408 const r = await req('PUT', `/api/v1/files/content?path=${vq('/~/x.txt')}`, { token: aliceRead.access_token, body: 'x' });
409 expect(r.status).toBe(403);
410 expect(r.data.error).toBe('insufficient_scope');
411 });
412
413 test('cannot read roots without permission, other users folders, or escape via .. or symlinks', async () =>
414 {
415 expect((await req('GET', `/api/v1/files/content?path=${vq('/secret/secret.txt')}`, { token: alice.access_token })).status).toBe(404);
416 fs.mkdirSync(path.join(USERS_DIR, 'bob'), { recursive: true });
417 fs.writeFileSync(path.join(USERS_DIR, 'bob', 'private.txt'), 'bob only');
418 const viaHome = await req('GET', `/api/v1/files/content?path=${vq('/~/private.txt')}`, { token: alice.access_token });
419 expect(viaHome.status).toBe(404);
420 expect((await req('GET', `/api/v1/files/content?path=${vq('/~/../bob/private.txt')}`, { token: alice.access_token })).status).toBe(400);
421 expect((await req('GET', `/api/v1/files/content?path=${vq('/~/private.txt')}`, { token: bob.access_token })).text).toBe('bob only');
422
423 fs.mkdirSync(path.join(USERS_DIR, 'alice'), { recursive: true });
424 fs.symlinkSync(ROOTS.secret, path.join(USERS_DIR, 'alice', 'link'));
425 expect((await req('GET', `/api/v1/files/content?path=${vq('/~/link/secret.txt')}`, { token: alice.access_token })).status).toBe(404);
426 const list = await req('GET', `/api/v1/files/list?path=${vq('/~')}`, { token: alice.access_token });
427 expect(list.data.entries.some((e) => e.name === 'link')).toBe(false);
428 fs.unlinkSync(path.join(USERS_DIR, 'alice', 'link'));
429 });
430
431 test('read-only roots cannot be written even with files:write', async () =>
432 {
433 const r = await req('PUT', `/api/v1/files/content?path=${vq('/shared/new.txt')}`, { token: alice.access_token, body: 'x' });
434 expect(r.status).toBe(403);
435 expect(fs.existsSync(path.join(ROOTS.shared, 'new.txt'))).toBe(false);
436 const b = await req('POST', '/api/v1/folders', { token: bob.access_token, json: { path: '/team/x' } });
437 expect(b.status).toBe(403);
438 });
439
440 test('admin users get admin-level access, nothing more', async () =>
441 {
442 const root = await login('root');
443 const r = await req('GET', '/api/v1/roots', { token: root.access_token });
444 expect(r.data.roots.map((x) => x.id)).toEqual(['~', 'shared', 'team', 'secret']);
445 });
446});
447
448describe('Files: upload, download, conflicts', () =>
449{
450 let t;
451 beforeAll(async () => { t = await login('alice'); });
452
453 test('simple upload, conditional overwrite and conflicts', async () =>
454 {
455 const mtime = Date.parse('2024-01-02T03:04:05.000Z');
456 const up = await req('PUT', `/api/v1/files/content?path=${vq('/team/a.txt')}&mtime=${mtime}`, { token: t.access_token, body: 'hello' });
457 expect(up.status).toBe(201);
458 expect(up.data).toMatchObject({ path: '/team/a.txt', type: 'file', size: 5, mtime_ms: mtime });
459 expect(up.data.sha256).toBe(crypto.createHash('sha256').update('hello').digest('hex'));
460 expect(fs.readFileSync(path.join(ROOTS.team, 'a.txt'), 'utf8')).toBe('hello');
461
462 const conflict = await req('PUT', `/api/v1/files/content?path=${vq('/team/a.txt')}`, { token: t.access_token, body: 'x' });
463 expect(conflict.status).toBe(409);
464 expect(conflict.data.current.version).toBe(up.data.version);
465
466 const noneMatch = await req('PUT', `/api/v1/files/content?path=${vq('/team/a.txt')}`, { token: t.access_token, body: 'x', headers: { 'If-None-Match': '*' } });
467 expect(noneMatch.status).toBe(412);
468
469 const stale = await req('PUT', `/api/v1/files/content?path=${vq('/team/a.txt')}`, { token: t.access_token, body: 'x', headers: { 'If-Match': '"stale"' } });
470 expect(stale.status).toBe(412);
471
472 const ok = await req('PUT', `/api/v1/files/content?path=${vq('/team/a.txt')}`, { token: t.access_token, body: 'hello world', headers: { 'If-Match': `"${up.data.version}"` } });
473 expect(ok.status).toBe(200);
474 expect(ok.data.version).not.toBe(up.data.version);
475 expect(ok.headers.get('etag')).toBe(`"${ok.data.version}"`);
476
477 const forced = await req('PUT', `/api/v1/files/content?path=${vq('/team/a.txt')}&overwrite=true`, { token: t.access_token, body: 'hello world!' });
478 expect(forced.status).toBe(200);
479 });
480
481 test('upload into a missing folder fails cleanly and leaves no temp files', async () =>
482 {
483 const r = await req('PUT', `/api/v1/files/content?path=${vq('/team/nope/a.txt')}`, { token: t.access_token, body: 'x' });
484 expect(r.status).toBe(409);
485 expect(r.data.error).toBe('parent_missing');
486 expect(fs.readdirSync(ROOTS.team).some((n) => n.startsWith('.fmapi-'))).toBe(false);
487 });
488
489 test('checksum mismatch is refused', async () =>
490 {
491 const r = await req('PUT', `/api/v1/files/content?path=${vq('/team/sum.txt')}`, { token: t.access_token, body: 'abc', headers: { 'X-Content-SHA256': '0'.repeat(64) } });
492 expect(r.status).toBe(422);
493 expect(fs.existsSync(path.join(ROOTS.team, 'sum.txt'))).toBe(false);
494 });
495
496 test('download supports ETag, 304 and Range', async () =>
497 {
498 const meta = await req('GET', `/api/v1/files/metadata?path=${vq('/team/a.txt')}`, { token: t.access_token });
499 const full = await req('GET', `/api/v1/files/content?path=${vq('/team/a.txt')}`, { token: t.access_token });
500 expect(full.status).toBe(200);
501 expect(full.text).toBe('hello world!');
502 expect(full.headers.get('etag')).toBe(`"${meta.data.version}"`);
503
504 const cached = await req('GET', `/api/v1/files/content?path=${vq('/team/a.txt')}`, { token: t.access_token, headers: { 'If-None-Match': `"${meta.data.version}"` } });
505 expect(cached.status).toBe(304);
506
507 const part = await req('GET', `/api/v1/files/content?path=${vq('/team/a.txt')}`, { token: t.access_token, headers: { Range: 'bytes=6-10' } });
508 expect(part.status).toBe(206);
509 expect(part.text).toBe('world');
510 expect(part.headers.get('content-range')).toBe('bytes 6-10/12');
511 });
512
513 test('metadata can compute a hash on demand for files changed outside the API', async () =>
514 {
515 fs.writeFileSync(path.join(ROOTS.team, 'outside.bin'), 'outside');
516 const m1 = await req('GET', `/api/v1/files/metadata?path=${vq('/team/outside.bin')}`, { token: t.access_token });
517 expect(m1.data.sha256).toBeNull();
518 const m2 = await req('GET', `/api/v1/files/metadata?path=${vq('/team/outside.bin')}&hash=1`, { token: t.access_token });
519 expect(m2.data.sha256).toBe(crypto.createHash('sha256').update('outside').digest('hex'));
520 });
521
522 test('folders, listing, move and delete', async () =>
523 {
524 expect((await req('POST', '/api/v1/folders', { token: t.access_token, json: { path: '/team/docs/sub', parents: true } })).status).toBe(201);
525 expect((await req('POST', '/api/v1/folders', { token: t.access_token, json: { path: '/team/docs' } })).status).toBe(409);
526 expect((await req('POST', '/api/v1/folders', { token: t.access_token, json: { path: '/team/docs', exist_ok: true } })).status).toBe(200);
527 await req('PUT', `/api/v1/files/content?path=${vq('/team/docs/b.txt')}`, { token: t.access_token, body: 'b' });
528
529 const list = await req('GET', `/api/v1/files/list?path=${vq('/team/docs')}&limit=1`, { token: t.access_token });
530 expect(list.data.entries).toHaveLength(1);
531 expect(list.data.next_page_token).toBe('1');
532
533 const mv = await req('POST', '/api/v1/files/move', { token: t.access_token, json: { from: '/team/docs/b.txt', to: '/team/docs/sub/c.txt' } });
534 expect(mv.status).toBe(200);
535 expect(mv.data.path).toBe('/team/docs/sub/c.txt');
536
537 await req('PUT', `/api/v1/files/content?path=${vq('/team/docs/d.txt')}`, { token: t.access_token, body: 'd' });
538 const clash = await req('POST', '/api/v1/files/move', { token: t.access_token, json: { from: '/team/docs/d.txt', to: '/team/docs/sub/c.txt' } });
539 expect(clash.status).toBe(409);
540 const into = await req('POST', '/api/v1/files/move', { token: t.access_token, json: { from: '/team/docs', to: '/team/docs/sub/x' } });
541 expect(into.status).toBe(400);
542 const toReadOnly = await req('POST', '/api/v1/files/move', { token: t.access_token, json: { from: '/team/docs/d.txt', to: '/shared/d.txt' } });
543 expect(toReadOnly.status).toBe(403);
544
545 expect((await req('DELETE', `/api/v1/files?path=${vq('/team/docs')}`, { token: t.access_token })).status).toBe(409);
546 expect((await req('DELETE', `/api/v1/files?path=${vq('/team/docs/d.txt')}`, { token: t.access_token, headers: { 'If-Match': '"old"' } })).status).toBe(412);
547 expect((await req('DELETE', `/api/v1/files?path=${vq('/team/docs')}&recursive=true`, { token: t.access_token })).status).toBe(204);
548 expect(fs.existsSync(path.join(ROOTS.team, 'docs'))).toBe(false);
549 expect((await req('DELETE', `/api/v1/files?path=${vq('/team')}`, { token: t.access_token })).status).toBe(400);
550 });
551
552 test('errors are JSON, also for unknown endpoints', async () =>
553 {
554 const r = await req('GET', '/api/v1/nope', { token: t.access_token });
555 expect(r.status).toBe(404);
556 expect(r.data.error).toBe('not_found');
557 const bad = await req('GET', '/api/v1/files/metadata?path=relative', { token: t.access_token });
558 expect(bad.data.error).toBe('invalid_path');
559 });
560});
561
562describe('Resumable uploads', () =>
563{
564 let t;
565 let other;
566 beforeAll(async () => { t = await login('alice'); other = await login('alice'); });
567
568 test('chunked upload with offsets, resume info and checksum', async () =>
569 {
570 const content = crypto.randomBytes(2.5 * 1024 * 1024);
571 const sha = crypto.createHash('sha256').update(content).digest('hex');
572 const c = await req('POST', '/api/v1/uploads', { token: t.access_token, json: { path: '/team/big.bin', size: content.length, sha256: sha, mtime: 1700000000000 } });
573 expect(c.status).toBe(201);
574 const id = c.data.id;
575 expect(c.data.max_chunk_bytes).toBe(1024 * 1024);
576
577 // Another grant (even of the same user) cannot touch this session.
578 expect((await req('GET', `/api/v1/uploads/${id}`, { token: other.access_token })).status).toBe(404);
579
580 const tooBig = await req('PATCH', `/api/v1/uploads/${id}`, { token: t.access_token, headers: { 'Upload-Offset': '0' }, body: content.subarray(0, 1024 * 1024 + 1) });
581 expect(tooBig.status).toBe(413);
582 expect((await req('GET', `/api/v1/uploads/${id}`, { token: t.access_token })).data.offset).toBe(0);
583
584 let offset = 0;
585 while (offset < content.length)
586 {
587 const chunk = content.subarray(offset, offset + 1024 * 1024);
588 const p = await req('PATCH', `/api/v1/uploads/${id}`, { token: t.access_token, headers: { 'Upload-Offset': String(offset) }, body: chunk });
589 expect(p.status).toBe(200);
590 offset = p.data.offset;
591 if (offset === 1024 * 1024)
592 {
593 const wrong = await req('PATCH', `/api/v1/uploads/${id}`, { token: t.access_token, headers: { 'Upload-Offset': '0' }, body: 'x' });
594 expect(wrong.status).toBe(409);
595 expect(wrong.data.offset).toBe(1024 * 1024);
596 const early = await req('POST', `/api/v1/uploads/${id}/complete`, { token: t.access_token });
597 expect(early.status).toBe(409);
598 }
599 }
600 const done = await req('POST', `/api/v1/uploads/${id}/complete`, { token: t.access_token });
601 expect(done.status).toBe(201);
602 expect(done.data).toMatchObject({ path: '/team/big.bin', size: content.length, sha256: sha, mtime_ms: 1700000000000 });
603 expect(fs.readFileSync(path.join(ROOTS.team, 'big.bin')).equals(content)).toBe(true);
604 expect(fs.readdirSync(mockConfig.api.uploadDir)).toEqual([]);
605 });
606
607 test('checksum mismatch discards the upload', async () =>
608 {
609 const c = await req('POST', '/api/v1/uploads', { token: t.access_token, json: { path: '/team/bad.bin', size: 3, sha256: '0'.repeat(64) } });
610 await req('PATCH', `/api/v1/uploads/${c.data.id}`, { token: t.access_token, headers: { 'Upload-Offset': '0' }, body: 'abc' });
611 const r = await req('POST', `/api/v1/uploads/${c.data.id}/complete`, { token: t.access_token });
612 expect(r.status).toBe(422);
613 expect(fs.existsSync(path.join(ROOTS.team, 'bad.bin'))).toBe(false);
614 });
615
616 test('preconditions are checked at start and at completion', async () =>
617 {
618 const exists = await req('POST', '/api/v1/uploads', { token: t.access_token, json: { path: '/team/big.bin', size: 1 } });
619 expect(exists.status).toBe(409);
620 const c = await req('POST', '/api/v1/uploads', { token: t.access_token, json: { path: '/team/race.txt', size: 1, if_none_match: '*' } });
621 await req('PATCH', `/api/v1/uploads/${c.data.id}`, { token: t.access_token, headers: { 'Upload-Offset': '0' }, body: 'z' });
622 fs.writeFileSync(path.join(ROOTS.team, 'race.txt'), 'someone else');
623 const r = await req('POST', `/api/v1/uploads/${c.data.id}/complete`, { token: t.access_token });
624 expect(r.status).toBe(412);
625 expect(fs.readFileSync(path.join(ROOTS.team, 'race.txt'), 'utf8')).toBe('someone else');
626 });
627
628 test('cancel removes the staged data', async () =>
629 {
630 const c = await req('POST', '/api/v1/uploads', { token: t.access_token, json: { path: '/team/cancel.bin', size: 10 } });
631 expect((await req('DELETE', `/api/v1/uploads/${c.data.id}`, { token: t.access_token })).status).toBe(204);
632 expect((await req('GET', `/api/v1/uploads/${c.data.id}`, { token: t.access_token })).status).toBe(404);
633 });
634});
635
636describe('Delta feed', () =>
637{
638 let t;
639 let bob;
640 beforeAll(async () => { t = await login('alice'); bob = await login('bob'); });
641
642 async function drain (cursor)
643 {
644 const all = [];
645 let c = cursor;
646 for (;;)
647 {
648 const r = await req('GET', `/api/v1/delta?root=${vq('~')}&cursor=${c}&limit=2`, { token: t.access_token });
649 expect(r.status).toBe(200);
650 all.push(...r.data.entries);
651 c = r.data.cursor;
652 if (!r.data.has_more) return { entries: all, cursor: c };
653 }
654 }
655
656 test('snapshot, then created/modified/moved/deleted incl. changes made outside the API', async () =>
657 {
658 const home = path.join(USERS_DIR, 'alice');
659 fs.mkdirSync(path.join(home, 'photos'), { recursive: true });
660 fs.writeFileSync(path.join(home, 'photos', '1.jpg'), 'one');
661 fs.writeFileSync(path.join(home, 'notes.txt'), 'n');
662
663 // Initial snapshot, paged.
664 let r = await req('GET', `/api/v1/delta?root=${vq('~')}&limit=2`, { token: t.access_token });
665 expect(r.data.reset).toBe(true);
666 const snap = [...r.data.entries];
667 let cursor = r.data.cursor;
668 while (r.data.has_more)
669 {
670 r = await req('GET', `/api/v1/delta?root=${vq('~')}&cursor=${cursor}&limit=2`, { token: t.access_token });
671 snap.push(...r.data.entries);
672 cursor = r.data.cursor;
673 }
674 expect(snap.map((e) => e.path).sort()).toEqual(expect.arrayContaining(['/~/notes.txt', '/~/photos', '/~/photos/1.jpg']));
675 expect(snap.every((e) => e.change === 'exists')).toBe(true);
676
677 // No changes.
678 let d = await drain(cursor);
679 expect(d.entries).toEqual([]);
680 cursor = d.cursor;
681
682 // Changes through the API.
683 await req('PUT', `/api/v1/files/content?path=${vq('/~/new.txt')}`, { token: t.access_token, body: 'new' });
684 await req('POST', '/api/v1/files/move', { token: t.access_token, json: { from: '/~/photos', to: '/~/pictures' } });
685 d = await drain(cursor);
686 cursor = d.cursor;
687 expect(d.entries).toEqual(expect.arrayContaining([
688 expect.objectContaining({ change: 'created', path: '/~/new.txt', type: 'file', size: 3 }),
689 expect.objectContaining({ change: 'moved', path: '/~/pictures', old_path: '/~/photos', type: 'folder' }),
690 ]));
691 // Children of a moved folder are implied, not repeated.
692 expect(d.entries.some((e) => e.path === '/~/pictures/1.jpg')).toBe(false);
693
694 // Changes made directly on disk / via the web UI.
695 await new Promise((res) => setTimeout(res, 20));
696 fs.writeFileSync(path.join(home, 'notes.txt'), 'changed notes');
697 fs.rmSync(path.join(home, 'pictures'), { recursive: true });
698 d = await drain(cursor);
699 cursor = d.cursor;
700 expect(d.entries).toEqual(expect.arrayContaining([
701 expect.objectContaining({ change: 'modified', path: '/~/notes.txt', size: 13 }),
702 expect.objectContaining({ change: 'deleted', path: '/~/pictures', type: 'folder' }),
703 ]));
704 expect(d.entries.some((e) => e.path === '/~/pictures/1.jpg')).toBe(false);
705 const del = d.entries.find((e) => e.change === 'deleted');
706 expect(del.version).toBeNull();
707 });
708
709 test('cursor is bound to its root and unknown roots are hidden', async () =>
710 {
711 const r = await req('GET', `/api/v1/delta?root=${vq('~')}`, { token: t.access_token });
712 const other = await req('GET', `/api/v1/delta?root=team&cursor=${r.data.cursor}`, { token: t.access_token });
713 expect(other.status).toBe(400);
714 expect((await req('GET', '/api/v1/delta?root=secret', { token: t.access_token })).status).toBe(404);
715 expect((await req('GET', '/api/v1/delta?root=x&cursor=%%%', { token: t.access_token })).status).toBe(400);
716 });
717
718 test('another user sees their own home, not alice\'s', async () =>
719 {
720 const r = await req('GET', `/api/v1/delta?root=${vq('~')}&limit=1000`, { token: bob.access_token });
721 expect(r.data.entries.map((e) => e.path)).toEqual(['/~/private.txt']);
722 });
723
724 test('pruned history answers 410 so clients start over', async () =>
725 {
726 const r = await req('GET', '/api/v1/delta?root=team&limit=1000', { token: t.access_token });
727 expect(r.data.has_more).toBe(false);
728 getDb().prepare('UPDATE api_scan_state SET min_seq = min_seq + 100000 WHERE root_key = ?').run([ROOTS.team]);
729 const gone = await req('GET', `/api/v1/delta?root=team&cursor=${r.data.cursor}`, { token: t.access_token });
730 expect(gone.status).toBe(410);
731 expect(gone.data.error).toBe('cursor_expired');
732 });
733});