jrrribeiro commited on
Commit
0760ded
·
verified ·
1 Parent(s): 7af707c

Sync app from GitHub Actions (feature/project-state-security-privacy-review)

Browse files
docs/HF_ORGANIZATION_STORAGE_BACKEND_INVESTIGATION.md ADDED
@@ -0,0 +1,250 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Hugging Face Organization-Owned State Backend Investigation
2
+
3
+ Status: investigation and permission-spike plan; not approved for production
4
+ Created: 2026-05-25
5
+ Target branch: `feature/project-state-security-privacy-review`
6
+
7
+ ## Purpose
8
+
9
+ Evaluate whether a free Hugging Face organization owned and managed by each
10
+ project team can provide persistent, collaborative validation state without:
11
+
12
+ 1. storing an administrator token in the app;
13
+ 2. making the application maintainer pay for user project state;
14
+ 3. writing one Git commit per validation; or
15
+ 4. requiring a paid Hugging Face plan for ordinary projects.
16
+
17
+ This investigation follows two failed personal-resource experiments:
18
+
19
+ 1. A private Bucket owned by one user's personal namespace was not accessible
20
+ for validation by an invited second user using their own authorization.
21
+ 2. A private personal `_state` repository could be read through OAuth, but a
22
+ direct state commit was rejected and required a Pull Request. That is not a
23
+ suitable write path for rapid validation work.
24
+
25
+ ## Initial Decision
26
+
27
+ The organization candidate must be tested with an **organization-owned private
28
+ Storage Bucket** for validation events and snapshots, not a Git-backed dataset
29
+ repository as its frequent-write store.
30
+
31
+ Reason: Hugging Face documents Buckets as mutable object storage for changing
32
+ files, logs, and intermediate state, without Git history or Pull Requests.
33
+ Repositories remain useful only for infrequent metadata, export checkpoints, or
34
+ portable backups.
35
+
36
+ Proposed split, only if the permission test succeeds:
37
+
38
+ | Content | Candidate storage | Expected frequency |
39
+ |---|---|---|
40
+ | Audio and original detection index | Existing dataset, public or organization-shared if private | Read-only during validation |
41
+ | Project manifest and ACL policy | Small private organization repository or Bucket metadata files | Infrequent |
42
+ | Validation events and live snapshot | Private organization-owned Bucket | Frequent/batched writes |
43
+ | Scientific CSV/XLSX export checkpoint | Download on demand, optionally archived in project storage | Infrequent |
44
+
45
+ ## Confirmed From Official Hugging Face Documentation
46
+
47
+ ### Cost And Quota
48
+
49
+ 1. A free user **or free organization** currently includes `100GB` of private
50
+ Hub storage.
51
+ 2. Storage limits apply to repositories and Buckets.
52
+ 3. Storage above free allowances or upgraded organization features may incur
53
+ charges; a project must never be silently upgraded or attached to the
54
+ app maintainer's billing.
55
+
56
+ Practical consequence: a state-only Bucket is expected to remain small. A
57
+ private audio dataset also placed inside the organization consumes the same
58
+ private allowance; multiple large private audio projects can exceed `100GB`.
59
+ Public audio does not need to be duplicated into private validation state.
60
+
61
+ ### Write Performance Model
62
+
63
+ 1. Storage Buckets are available to users and organizations.
64
+ 2. Buckets are mutable, non-versioned storage and do not use Git commits or
65
+ Pull Requests.
66
+ 3. The Python client supports batch Bucket writes.
67
+ 4. Git-backed repositories are not intended to behave as frequently written
68
+ databases; the Hub notes degraded experience after thousands of commits.
69
+
70
+ Practical consequence: organization-owned Buckets are the only HF-native
71
+ candidate here that matches hundreds of fast decisions without generating a
72
+ commit stream.
73
+
74
+ ### Organization Access Control
75
+
76
+ Free organizations support member roles:
77
+
78
+ | Role | Relevant ability |
79
+ |---|---|
80
+ | `read` | Read organization repositories and metadata only |
81
+ | `contributor` | Write only repositories created by that member |
82
+ | `write` | Write, create, delete, or rename resources across the organization |
83
+ | `admin` | Administrative control |
84
+
85
+ Fine-grained Resource Groups are documented as part of **Team and Enterprise**
86
+ plans, not the free organization model.
87
+
88
+ Practical consequence: a free organization cannot yet be assumed to grant a
89
+ validator write access to only one project's private state resource. A
90
+ validator given organization-level write power may be able to modify other
91
+ resources in that same organization.
92
+
93
+ ### OAuth Scope Gap
94
+
95
+ The current app requests:
96
+
97
+ ```yaml
98
+ hf_oauth_scopes:
99
+ - read-repos
100
+ - contribute-repos
101
+ ```
102
+
103
+ Hugging Face documents that OAuth users may authorize selected organization
104
+ access. However, documentation does not establish that the current app scopes
105
+ permit direct write access to an organization-owned private Bucket for an
106
+ organization member.
107
+
108
+ Practical consequence: no OAuth scope change should be deployed as a product
109
+ feature until a small organization Bucket permission spike succeeds.
110
+
111
+ ## Security Assessment
112
+
113
+ ### What This Model Would Solve
114
+
115
+ If proven, it would provide:
116
+
117
+ 1. State owned by the project team organization, not by this app maintainer.
118
+ 2. Each validator authenticating with their own Hugging Face identity.
119
+ 3. Mutable state writes without Git commit limits.
120
+ 4. Persistence across Space deployments and restarts.
121
+
122
+ ### What It Does Not Solve On The Free Tier
123
+
124
+ It does not offer strong project-level isolation inside one shared organization.
125
+ Application ACL checks prevent normal UI misuse, but cannot prevent a member
126
+ with Hub-level write permission from modifying Bucket content outside the app.
127
+
128
+ Therefore:
129
+
130
+ 1. A single free organization containing unrelated projects is not acceptable
131
+ when validators must be isolated from each other's project data.
132
+ 2. A team organization is acceptable only where all users receiving write
133
+ access are trusted at the organization level.
134
+ 3. Creating one free organization per project might isolate projects, but it
135
+ must not be assumed to be a scalable or supported product design without
136
+ explicit validation of Hugging Face policy and operational burden.
137
+ 4. Paid Resource Groups would provide a stronger permission boundary, but
138
+ cannot be a requirement for the free default workflow.
139
+
140
+ ## Private And Public Dataset Scenarios
141
+
142
+ | Audio dataset | Organization state Bucket | Validator requirement | Candidate result |
143
+ |---|---|---|---|
144
+ | Public personal dataset | Private organization Bucket | Write access to state Bucket only | Best free candidate to test |
145
+ | Private organization dataset | Private organization Bucket | Read audio and write state | Testable, but audio counts toward private quota |
146
+ | Private personal admin dataset | Private organization Bucket | Personal dataset sharing still unresolved | Not a complete collaborative solution |
147
+
148
+ The first permission spike should use a public dataset and tiny fake state so
149
+ that it tests state authorization only, not private audio sharing.
150
+
151
+ ## Permission Spike: No App Changes Yet
152
+
153
+ ### Goal
154
+
155
+ Prove whether two free accounts can read and write a private
156
+ organization-owned Bucket with their own Hugging Face credentials, and
157
+ document the minimum organization role required.
158
+
159
+ ### Setup
160
+
161
+ 1. Create one temporary free Hugging Face organization for the spike.
162
+ 2. The admin account creates a private Bucket inside that organization, for
163
+ example `<test-org>/validator-state-permission-test`.
164
+ 3. Do not upload real recordings or validation data; use two small JSON files.
165
+ 4. Invite the second account into the organization first as `contributor`.
166
+
167
+ ### Credential Test A: User Tokens Outside The App
168
+
169
+ This isolates Hugging Face permission behavior before changing OAuth scopes.
170
+
171
+ 1. Admin writes `diagnostics/admin-write.json` to the Bucket using the admin's
172
+ own temporary token.
173
+ 2. Validator attempts to read that file using the validator's own token.
174
+ 3. Validator attempts to write `diagnostics/validator-contributor-write.json`
175
+ using their own token while assigned `contributor`.
176
+ 4. If the write fails, change only the test member role to `write`.
177
+ 5. Validator attempts `diagnostics/validator-write-role-write.json`.
178
+ 6. Admin reads the validator file using the admin token.
179
+
180
+ Expected likely result based on the role documentation: `contributor` is
181
+ insufficient because the validator did not create the admin-created Bucket;
182
+ `write` may succeed but grants organization-wide write powers.
183
+
184
+ ### Credential Test B: OAuth In The Space
185
+
186
+ Run only if Test A proves an acceptable organization permission model.
187
+
188
+ 1. Add a narrowly scoped experimental OAuth/Bucket diagnostic in this feature
189
+ branch only.
190
+ 2. Request only the organization-capable scope proven necessary by an
191
+ explicit test; never store returned OAuth tokens in project state.
192
+ 3. Admin signs in through OAuth and writes one diagnostic object.
193
+ 4. Validator signs in through OAuth and writes a second diagnostic object.
194
+ 5. Admin confirms both files and the actor identity recorded in each object.
195
+
196
+ Pass condition: both authenticated users can directly write private state using
197
+ their own authorization, without PRs or shared tokens.
198
+
199
+ Fail condition: either account cannot write, writes require an admin token, or
200
+ OAuth forces broader access than accepted by the security policy.
201
+
202
+ ### Throughput Test C: Batch Validation Writes
203
+
204
+ Run only if both permission tests pass.
205
+
206
+ 1. Generate simulated validation events with no audio data.
207
+ 2. Test batches of `25`, `100`, and `250` decisions per Bucket write.
208
+ 3. Measure write latency, read/reconciliation latency, conflicts, and rate
209
+ limit responses with two simultaneous users.
210
+ 4. Confirm export reconstruction and recovery after application restart.
211
+
212
+ Pass condition: validation remains responsive at the expected working rate
213
+ (approximately one decision every three seconds per active validator) without
214
+ Git commits and without data loss.
215
+
216
+ ## Gate For Implementation
217
+
218
+ Do not implement this backend as the app default unless all items are true:
219
+
220
+ 1. An organization-owned Bucket can be written by both test accounts using
221
+ only their own authorization.
222
+ 2. The required free-tier role and its security implications are acceptable
223
+ for the intended project governance.
224
+ 3. The test does not require paid Resource Groups.
225
+ 4. The project owner explicitly accepts that state and any private audio stored
226
+ in a free organization share its current `100GB` private allowance.
227
+ 5. Batch stress testing confirms that fast validation does not lose state.
228
+
229
+ If Test A requires organization-wide `write`, the decision is not purely
230
+ technical: this model can support trusted research teams, but not isolated
231
+ arbitrary validators in a multi-project free organization.
232
+
233
+ ## Most Likely Product Options After The Spike
234
+
235
+ | Option | Cost requirement | Isolation | Current assessment |
236
+ |---|---:|---|---|
237
+ | Free organization Bucket for a trusted team/project | None within current free quota | Organization-level only | Worth permission spike |
238
+ | One free organization for many unrelated projects | None within quota | Insufficient without paid Resource Groups | Not acceptable default |
239
+ | Team/Enterprise Resource Groups | Paid | Project/resource scoped | Secure optional tier only |
240
+ | Admin-provided external database | Depends on admin provider/free tier | Strongly project-owned when configured correctly | Remains fallback/default candidate |
241
+
242
+ ## Official References
243
+
244
+ - Hugging Face organizations: <https://huggingface.co/docs/hub/organizations>
245
+ - Organization access control: <https://huggingface.co/docs/hub/organizations-security>
246
+ - Resource Groups: <https://huggingface.co/docs/hub/security-resource-groups>
247
+ - OAuth scopes and organization authorization: <https://huggingface.co/docs/hub/oauth>
248
+ - Storage Buckets: <https://huggingface.co/docs/hub/storage-buckets>
249
+ - Storage limits: <https://huggingface.co/docs/hub/storage-limits>
250
+ - Hub rate limits: <https://huggingface.co/docs/hub/rate-limits>
docs/HF_PRIVATE_STATE_OAUTH_BATCHING_IMPLEMENTATION_PLAN.md CHANGED
@@ -430,6 +430,10 @@ Evaluate in this order:
430
  3. A paid or institution-supported organization architecture only as an
431
  optional advanced deployment, never as the default requirement for users.
432
 
 
 
 
 
433
  ## Implementation Order
434
 
435
  Do not implement batching first. The correct order is:
 
430
  3. A paid or institution-supported organization architecture only as an
431
  optional advanced deployment, never as the default requirement for users.
432
 
433
+ The organization-owned Storage Bucket investigation and permission-spike gate
434
+ are documented in
435
+ [`HF_ORGANIZATION_STORAGE_BACKEND_INVESTIGATION.md`](HF_ORGANIZATION_STORAGE_BACKEND_INVESTIGATION.md).
436
+
437
  ## Implementation Order
438
 
439
  Do not implement batching first. The correct order is: