Sync-API v1 met OAuth2 (code+PKCE) toestemming, delta-feed, resumable uploads en docs
- /oauth/authorize (consentpagina), /oauth/token (code+PKCE S256, refresh-rotatie met hergebruikdetectie), /oauth/revoke, RFC 8414 metadata - /api/v1: roots, metadata, list, download (Range/ETag), upload (If-Match/If-None-Match), folders, move, delete, delta met cursor, resumable uploads - /apps.html + /api/account/api-access: verleende toegang zien/intrekken, persoonlijke tokens, OAuth-clients (admin) - Tokens alleen gehasht opgeslagen; API gebruikt dezelfde permissiecontroles als de web-UI - docs/api.md + docs/openapi.json, tests/api.v1.test.js
@@ -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
---@@ -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/10
logs.txt
10
logs.txt
11
11
12
*.db-journal12
*.db-journal13
api-uploads/@@ -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
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 user5
consent, listing, a change feed (delta), upload (including resumable6
uploads for large files), download with Range, folders, move, delete and7
conflict detection.8
9
- Machine-readable spec: [`docs/openapi.json`](openapi.json). A running10
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 they13
can see every authorised app, device and token, see when each was last14
used, revoke them, and create personal tokens.15
16
A token can never see more than its user can. Every request goes through17
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". You23
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 PKCE25
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=code43
&client_id=fmc_...44
&redirect_uri=com.example.sync:/callback45
&scope=files:read%20files:write46
&state=<random>47
&code_challenge=<challenge>&code_challenge_method=S25648
&device_name=Tim's%20Pixel49
```50
51
The user sees which app, which device and which permissions are52
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 for55
10 minutes and works only once. If the user denied access, you get56
`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
```json66
{"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. An71
access token is valid for 1 hour. Renew it with72
`grant_type=refresh_token&client_id=...&refresh_token=...`.73
**Refresh tokens rotate**: always store the new one. If an old refresh74
token is used again, the whole grant is revoked, because that points to75
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 own79
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 the82
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 on86
`/apps.html`. They are used the same way (`Authorization: Bearer`), can87
optionally expire, and can be revoked there.88
89
## 3. Paths and roots90
91
`GET /api/v1/roots` returns the roots the user can see. `~` is always the92
user's own folder. Other roots are the shared folders the user has rights93
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 segments95
`..` 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 walkthrough109
110
```text111
# First sync of a root112
GET /api/v1/delta?root=~ -> reset=true, entries(change=exists), cursor, has_more113
GET /api/v1/delta?root=~&cursor=<c> -> repeat while has_more114
store cursor115
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 copy120
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 cursor123
410 cursor_expired -> start over without a cursor and reconcile with local state124
```125
126
The feed sees all changes: those made through the API, through the web127
UI, and directly on disk. Changes from outside the API become visible128
within about 15 seconds (`api.scanIntervalSeconds`). Changes made through129
the API show up right away.130
131
Pushing local changes:132
133
```text134
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 there139
POST /uploads/<id>/complete140
rename/move: POST /files/move {from,to,if_match}141
delete : DELETE /files?path=..&recursive=true + If-Match142
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`, or148
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 approach152
is to save your local copy under a new name, such as153
`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 after157
the size and SHA-256 are verified, with an atomic rename. That way other158
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 returns162
304. The `ETag` is the `version`.163
164
**Delete is permanent.** The file manager has no trash, so ask the user165
for confirmation before you delete.166
167
## 5. Errors and limits168
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` under186
`"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 the200
API. The change history is kept for 30 days.201
202
## 6. Example (curl, personal token)203
204
```bash205
T=fmp_...; H="Authorization: Bearer $T"; S=https://files.example.com/api/v1206
curl -H "$H" $S/roots207
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.txt209
curl -H "$H" "$S/delta?root=~"210
```@@ -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": true141
},142
"mtime_ms": {143
"type": "integer",144
"nullable": true145
},146
"version": {147
"type": "string",148
"nullable": true149
}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": true380
}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,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 & 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 & 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 & 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 & 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,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
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,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, '&').replace(/</g, '<').replace(/>/g, '>')
31
.replace(/"/g, '"').replace(/'/g, ''');
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 clients5
// (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, '&').replace(/</g, '<').replace(/>/g, '>')31
.replace(/"/g, '"').replace(/'/g, ''');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 NOT71
* redirect (unknown client or redirect URI), { redirectError } for errors72
* 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
try193
{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,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 authorised4
// 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 hour11
const REFRESH_TOKEN_TTL_MS = 90 * 24 * 60 * 60 * 1000; // 90 days, sliding12
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 INTEGER30
);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 TEXT48
);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 NULL58
);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 NULL70
);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 NULL95
);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 0104
);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 NULL111
);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 NULL127
);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
// Clients164
// ---------------------------------------------------------------------------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:/cb189
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
try231
{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 codes240
// ---------------------------------------------------------------------------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 tokens272
// ---------------------------------------------------------------------------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 rotated313
* 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 is370
* 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_id412
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,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, the4
// API or directly on disk, so instead of hooking every writer we keep a5
// snapshot per root (api_entries) and diff it against the filesystem. The6
// 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
try63
{64
dirents = await fs.promises.readdir(path.join(rootAbs, rel), { withFileTypes: true });65
} catch66
{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
} else140
{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
try201
{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
} else236
{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,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
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
// Helpers44
// ---------------------------------------------------------------------------45
46
class ApiError extends Error47
{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
try191
{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=true257
*/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
} else304
{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
// Routes350
// ---------------------------------------------------------------------------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
try474
{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 replace486
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
} finally496
{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
} else515
{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
} else576
{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 feed588
// ---------------------------------------------------------------------------589
590
function encodeCursor (obj)591
{592
return Buffer.from(JSON.stringify(obj)).toString('base64url');593
}594
595
function decodeCursor (raw)596
{597
try598
{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
try628
{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 uploads678
// ---------------------------------------------------------------------------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
try767
{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
try808
{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;@@ -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
112
function closeDb ()114
function closeDb ()@@ -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');18
const filesRoutes = require('./routes/files');18
const filesRoutes = require('./routes/files');19
const adminRoutes = require('./routes/admin');19
const adminRoutes = require('./routes/admin');20
const shareRoutes = require('./routes/share');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
const { startShareMaintenanceLoop, stopShareMaintenanceLoop } = require('./routes/share');24
const { startShareMaintenanceLoop, stopShareMaintenanceLoop } = require('./routes/share');22
25
23
const app = express();26
const app = express();24
27
28
// Public sync API and OAuth endpoints. Mounted before the global JSON parser29
// so raw uploads are streamed untouched.30
app.use(oauthRoutes);31
app.use('/api/v1', apiV1Routes);32
25
app.use(express.json({ limit: '50mb' }));33
app.use(express.json({ limit: '50mb' }));26
app.use('/vendor/video.js', express.static(path.join(__dirname, '../node_modules/video.js/dist')));34
app.use('/vendor/video.js', express.static(path.join(__dirname, '../node_modules/video.js/dist')));27
app.use(express.static(path.join(__dirname, '../public')));35
app.use(express.static(path.join(__dirname, '../public')));@@ -30,6 +38,7 @@ app.use('/api/auth', authRoutes);30
app.use('/api/files', filesRoutes);38
app.use('/api/files', filesRoutes);31
app.use('/api/admin', adminRoutes);39
app.use('/api/admin', adminRoutes);32
app.use('/api/share', shareRoutes);40
app.use('/api/share', shareRoutes);41
app.use('/api/account/api-access', apiAccountRoutes);33
42
34
app.use((err, req, res, next) =>43
app.use((err, req, res, next) =>35
{44
{@@ -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.2477
router.helpers = {2478
loadConfigAndRoots,2479
resolveRootForUser,2480
canRead,2481
canReadInfo,2482
canWriteInfo,2483
getUserFolderPath,2484
checkUserFolderSizeLimit,2485
rewriteMetaPaths,2486
movePathWithFallback,2487
};2488
2476
module.exports = router;2489
module.exports = router;@@ -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 <8>');
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
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 <8>');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
});