Spaces:
Sleeping
Sleeping
File size: 15,968 Bytes
9cce5d1 fbd4a81 9cce5d1 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 | # HF Organization-Per-Project App Redesign Plan
Status: proposed target architecture after official API review and Bucket permission spike
Created: 2026-05-26
Target branch: `feature/project-state-security-privacy-review`
## Decision Summary
The target model is:
1. One Hugging Face organization represents one scientific validation project.
2. The project's private audio dataset, validation Bucket, manifest, and
members belong to that organization.
3. The BirdNET Validator Space remains a central, reusable application outside
project organizations and owns no project data.
4. Administrators manage projects primarily through the app, while the app
uses supported Hugging Face organization, repository, and Bucket APIs.
5. For free organizations, organization creation and the initial invitation or
role assignment of members remain Hugging Face web-interface steps because
no supported free API flow was found for the app to perform them.
This model accepts that a trusted validator requires organization-level
`write` access within one project organization. It prevents that permission
from reaching unrelated scientific projects by isolating each project in a
separate organization.
## Evidence Already Collected
### Real Permission Spike In `ppbio-rabeca`
On 2026-05-25, the app investigation created:
```text
ppbio-rabeca/birdnet-validator-permission-spike
```
The following results were measured with separate user tokens:
| User | Organization role | Read private Bucket | Write private Bucket |
|---|---|---:|---:|
| `jrrribeiro` | `admin` | Passed | Passed |
| `jonathan2008r` | `write` | Passed | Passed |
| `jonathan2008r` | `contributor` | Passed | Failed with `403` |
Result: on a free organization, validators who persist decisions in an
administrator-created private Bucket must be trusted `write` members.
### Official HfApi / Hub API Review
The official Python API and the installed `huggingface_hub` client expose:
| Capability | Official support observed | Use in app |
|---|---:|---|
| Create private dataset repository in an organization namespace (`create_repo`) | Yes | Project initialization |
| Create private organization Bucket (`create_bucket`) | Yes | Validation state initialization |
| Read/write/list Bucket files (`batch_bucket_files`, `download_bucket_files`, `list_bucket_tree`) | Yes | Validation and recovery |
| List organization Buckets (`list_buckets(namespace=...)`) | Yes | Project discovery/health |
| Get organization overview (`get_organization_overview`) | Yes | Verify organization |
| List organization members (`list_organization_members`) | Yes | Render membership/readiness |
| Create organization | Not exposed in reviewed HfApi/docs | External HF onboarding step |
| Invite a non-member into an organization | Not provided in reviewed supported API guide | External HF onboarding step |
| Change an existing member's organization role by API | Official Hub endpoint, subscription required | Not available as free default |
The official **Programmatic User Access Control Management** guide documents:
```text
PUT /api/organizations/{org_name}/members/{username}/role
```
but requires:
1. an organization subscription plan, such as Team or Enterprise;
2. an authenticated organization member with `write` or `admin` permission;
3. a target user who is already a member of the organization; and
4. a fine-grained token with organization settings/member management access.
The endpoint returns `402` when the organization lacks the required
subscription. It therefore cannot be the default mechanism for free community
projects. The regular organization management documentation directs admins to
the Hugging Face Members settings interface to add members, send invites,
revoke membership, and change roles.
## Target Ownership Model
### Central App
```text
jrrribeiro/BirdNET-Validator-App
```
Responsibilities:
1. OAuth authentication and session-bound operations.
2. Project onboarding workflow.
3. Data loading, validation UI, dashboards, and exports.
4. Bucket state write batching, reconciliation, and auditing.
It must not durably own:
1. project audio;
2. detection tables;
3. project validation state;
4. project ACL as an alternate source of authorization; or
5. administrator or validator tokens.
### Project Organization
Example:
```text
ppbio-rabeca/
PPBIO-RABECA private dataset repository
PPBIO-RABECA-validation-state private Storage Bucket
```
Recommended project resources:
| Resource | Location | Purpose | Mutable? |
|---|---|---|---:|
| Audio segments | Private dataset repository | Scientific source recordings | No during validation |
| Detection index/CSV | Same private dataset | Source observations and metadata | No during validation |
| `project.json` manifest | Validation Bucket metadata prefix initially | Project discovery/configuration | Infrequent admin update |
| Validation events | Validation Bucket `events/` | Append-oriented authored decisions | Yes |
| Reconciled snapshots | Validation Bucket `snapshots/` | Fast queue/progress reads | Yes |
| Audit archives/checkpoints | Validation Bucket `archives/` | Durable reconstruction/export | Append-oriented |
The original dataset remains versioned in a dataset repository. The frequently
mutating validation state uses a Bucket to avoid Git commit pressure.
## Organization Roles As Authorization
For the first organization-owned architecture:
| HF organization role | App role | Allowed UI capabilities |
|---|---|---|
| `admin` | Project administrator | Resource setup, integrity checks, member overview, validation, export, archival operations |
| `write` | Trusted validator | Read source dataset, write decisions, view progress, export as permitted |
| `read` | Viewer | Read project/progress only; no validation write |
| `contributor` | Viewer or unsupported state | Cannot write admin-created Bucket; never present as active validator |
| No membership/access | No project visibility | No project data access |
The app must query actual Hub access rather than treating a local invitation as
authorization. The current internal ACL/invite system becomes legacy migration
support only, then can be removed after organization mode is stable.
## User Experience And Supported Automation
The app should present an ordinary project workflow even though Hugging Face
resources are used underneath.
### Create Project Workspace
User-facing flow:
1. Admin clicks **Create Project**.
2. Admin supplies project name and the slug of an existing dedicated HF
organization.
3. The app authenticates through OAuth and verifies the user has adequate
access to initialize resources.
4. The app creates the private dataset repository and private validation
Bucket in that organization.
5. The app writes the manifest and initial empty validation snapshot.
6. The app performs readiness checks and shows the created resource identifiers.
Supported automation:
| Step | App handles it? | Notes |
|---|---:|---|
| Validate existing organization | Yes | Hub API/client |
| Validate admin can create organization resources | Yes | Attempt/preflight and explicit errors |
| Create dataset | Yes | `create_repo(..., repo_type="dataset", private=True)` |
| Create Bucket | Yes | `create_bucket(..., private=True)` |
| Write initial manifest/state | Yes | Bucket API |
| Create the organization itself | No in free supported path | Link user to HF create organization page |
### Add Validators
The desired interface remains an app card named **Project Members**, but it
mirrors Hub authority.
Supported free-tier flow:
1. App lists current members and translates HF roles into app capabilities.
2. For a new validator, app explains that `write` is required and provides a
direct link/instructions to the project's organization Members page.
3. Admin invites/adds the user through Hugging Face.
4. Admin returns and clicks **Refresh members**; the app detects the member and
runs a readiness test.
Not supported as a free default:
1. Sending the actual organization membership invite through a supported API;
2. changing a member to `write` programmatically; or
3. removing organization membership programmatically.
Optional future paid feature:
If a project organization has a qualifying subscription, the app could support
role changes for existing members through the documented Hub endpoint, with a
separately authorized fine-grained organization-management credential. This
must never be required for free use.
## OAuth Boundary Still To Prove
The token spike proves Hub organization permission behavior, not the Space
OAuth permission granted to this app.
Official OAuth documentation confirms:
1. OAuth scopes can apply to organization resources selected by a user at
authorization time.
2. `read-repos`, `write-repos`, and `manage-repos` descriptions refer to
repositories; no reviewed scope description explicitly promises Bucket
write behavior.
3. An app may request a specific organization through `orgIds=ORG_ID` in its
authorization URL.
Therefore organization mode must not be implemented as production workflow
until a Space diagnostic proves:
| Actor | Required proof using OAuth only |
|---|---|
| Admin | Detect organization, read/create project resources or access test resources, write diagnostic Bucket marker |
| Validator `write` | Read private dataset, read Bucket, write diagnostic Bucket marker |
| Validator `read` or `contributor` | Cannot submit validation state |
No manual token may be entered for that proof.
## Data Safety Requirements
Because validators with `write` are trusted but technically broad within one
project organization:
1. One organization must contain only one scientific project.
2. Source audio/detection dataset must remain Git-backed and treated as
immutable once validation begins.
3. App validation flows must never issue dataset writes for validators.
4. Bucket decisions must include actor, timestamp, detection key, decision,
prior version, new version, and event ID.
5. Individual validation events remain auditable until compacted into
append-oriented archives.
6. Snapshots are derived acceleration artifacts, not the sole source of truth.
7. Admin receives export/checkpoint tools and an integrity health view.
8. The uploader must retain local/source backups before moving real datasets
into organization ownership.
## Required App Refactor
### Phase 0 - OAuth Organization/Bucket Capability Proof
Goal: close the one unresolved technical permission question.
Deliverables:
1. Add an experimental diagnostics card available only in the feature branch.
2. Use the active OAuth session, never manually entered tokens.
3. Configure the existing test organization and Bucket:
`ppbio-rabeca/birdnet-validator-permission-spike`.
4. Show read/write results and clear failure interpretation.
5. Test both `jrrribeiro` (`admin`) and `jonathan2008r` restored to `write`.
Exit gate: both accounts write distinct diagnostic markers through OAuth.
### Phase 1 - Organization Project Domain Model
Goal: model project ownership around an organization and resource references.
Deliverables:
1. New manifest schema containing organization, dataset repo id, validation
Bucket id, visibility, schema version, and initialized timestamp.
2. `OrganizationProjectService` that loads the manifest and verifies resource
availability.
3. Membership mapper converting HF member role to application capability.
4. Legacy internal-ACL projects continue reading until migrated; no silent
conversion.
### Phase 2 - Project Creation Wizard
Goal: keep the current easy create-project interaction while making the
organization the durable project owner.
Deliverables:
1. Request existing organization slug and project display name.
2. Check organization/resource permissions using OAuth.
3. Create private dataset and private Bucket automatically.
4. Initialize manifest and snapshots automatically.
5. Provide explicit incomplete-initialization recovery if any sub-step fails.
6. Do not store project tokens.
### Phase 3 - Membership-Based Access UX
Goal: replace misleading application invites with real HF readiness.
Deliverables:
1. Replace **User access and invitations** with **Project Members**.
2. List organization members and mapped app roles.
3. Show access requirements: validators must be trusted HF `write` members.
4. Provide a guided link to the HF Members page for add/change/remove actions
in free organizations.
5. Add **Refresh members** and per-member readiness diagnostics.
6. Hide validation/project resources from non-members.
### Phase 4 - Bucket-Backed Validation As Primary Store
Goal: use already-developed fast mutable storage behavior with project-owned
organization Bucket routing.
Deliverables:
1. Route validation event writes to the organization Bucket using acting user's
OAuth token.
2. Route snapshots, conflict recovery, progress, and CSV/XLSX exports from
Bucket state.
3. Enable bounded compaction/audit archives after load testing.
4. Never fall back to filesystem, Supabase, or admin credentials when an
organization write fails.
### Phase 5 - Dataset/Uploader Integration
Goal: allow administrators to provision the project in the app and send audio
to the created organization dataset efficiently.
Deliverables:
1. Surface the created dataset repo id for the uploader.
2. Update uploader/app integration documentation for organization destinations.
3. Preserve uploader index structure used by validation loading.
4. Add connection flow for existing organization datasets.
### Phase 6 - Migration And Removal Of Legacy Authorization
Goal: retire fragile centrally owned state after qualification.
Deliverables:
1. Migration preview for current Supabase/filesystem/experimental `_state`
projects.
2. State import into organization Bucket with counts and verification report.
3. Remove project token entry from normal UI.
4. Disable internal invites/ACL as authority in organization mode.
5. Keep legacy mode read-only or explicitly marked until users migrate.
## Testing Program
### Permission And Security Tests
1. OAuth admin Bucket write in Space.
2. OAuth `write` validator Bucket write in Space.
3. OAuth `read`/`contributor` user validation write rejected.
4. User outside organization cannot see dataset or Bucket data.
5. App stores no OAuth/admin tokens in manifest, Bucket events, logs, or
exports.
### Reliability Tests
1. Two validators write concurrently.
2. Duplicate submit is idempotent.
3. Snapshot conflict is recovered from authored events.
4. Restart/redeploy does not lose validation state.
5. Export reconstructs detections plus partial or completed validations.
### Scale Tests
1. Simulate decisions at approximately one action every three seconds per
validator.
2. Run multiple concurrent validators.
3. Test event archive/compaction windows at realistic project sizes.
4. Measure Bucket latency and Hub rate-limit responses.
5. Confirm no dataset commits are generated by validation activity.
## Implementation Gate
The next code change should be **Phase 0 only**. Do not begin the onboarding
refactor until the existing organization Bucket succeeds through Space OAuth
for both administrator and `write` validator.
## Official References
- HfApi Client: <https://huggingface.co/docs/huggingface_hub/en/package_reference/hf_api>
- Storage Buckets: <https://huggingface.co/docs/hub/storage-buckets>
- Python Bucket guide: <https://huggingface.co/docs/huggingface_hub/guides/buckets>
- Organization management: <https://huggingface.co/docs/hub/organizations-managing>
- Organization access control: <https://huggingface.co/docs/hub/organizations-security>
- Programmatic User Access Control Management: <https://huggingface.co/docs/hub/programmatic-user-access-control>
- OAuth / Sign in with HF: <https://huggingface.co/docs/hub/oauth>
|