Spaces:
Sleeping
Sleeping
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:
|