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

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

Browse files
docs/HF_ORGANIZATION_STORAGE_BACKEND_INVESTIGATION.md CHANGED
@@ -158,12 +158,61 @@ 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.
 
158
 
159
  ### Setup
160
 
161
+ 1. Organization created for the spike: `ppbio-rabeca` (non-profit, confirmed
162
+ publicly on 2026-05-25).
163
+ 2. The admin account creates a private Bucket inside that organization:
164
+ `ppbio-rabeca/birdnet-validator-permission-spike`.
165
  3. Do not upload real recordings or validation data; use two small JSON files.
166
  4. Invite the second account into the organization first as `contributor`.
167
 
168
+ ### Executable Probe Utility
169
+
170
+ The branch contains `scripts/probe_hf_org_bucket_access.py`. It uses the
171
+ currently authenticated local Hugging Face account and never prints or saves
172
+ tokens. Every remote write is a small diagnostic JSON object under
173
+ `diagnostics/organization-permission-spike/`.
174
+
175
+ Authenticate the admin account in the terminal:
176
+
177
+ ```powershell
178
+ hf auth login --force
179
+ python scripts\probe_hf_org_bucket_access.py identity
180
+ python scripts\probe_hf_org_bucket_access.py create
181
+ ```
182
+
183
+ Then invite the second account to `ppbio-rabeca` as `contributor`, authenticate
184
+ that account in the terminal, and run:
185
+
186
+ ```powershell
187
+ hf auth login --force
188
+ python scripts\probe_hf_org_bucket_access.py identity
189
+ python scripts\probe_hf_org_bucket_access.py read
190
+ python scripts\probe_hf_org_bucket_access.py write --role-label contributor
191
+ ```
192
+
193
+ If only the write command fails, change that second user's organization role to
194
+ `write` temporarily and run:
195
+
196
+ ```powershell
197
+ python scripts\probe_hf_org_bucket_access.py write --role-label write
198
+ ```
199
+
200
+ Finally authenticate the administrator again and verify the marker:
201
+
202
+ ```powershell
203
+ hf auth login --force
204
+ python scripts\probe_hf_org_bucket_access.py read
205
+ python scripts\probe_hf_org_bucket_access.py list
206
+ ```
207
+
208
+ Do not delete the Bucket until the test result has been recorded. Cleanup is
209
+ available only through an explicit confirmation:
210
+
211
+ ```powershell
212
+ python scripts\probe_hf_org_bucket_access.py delete `
213
+ --confirm-delete ppbio-rabeca/birdnet-validator-permission-spike
214
+ ```
215
+
216
  ### Credential Test A: User Tokens Outside The App
217
 
218
  This isolates Hugging Face permission behavior before changing OAuth scopes.
scripts/probe_hf_org_bucket_access.py ADDED
@@ -0,0 +1,202 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Run a minimal two-account permission proof against an organization HF Bucket.
2
+
3
+ The script uses only the active Hugging Face credential available to
4
+ ``huggingface_hub``. It never prints or stores tokens and writes only tiny
5
+ diagnostic JSON files in the chosen test Bucket.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import argparse
11
+ import json
12
+ import re
13
+ import sys
14
+ from datetime import datetime, timezone
15
+ from pathlib import Path
16
+ from tempfile import TemporaryDirectory
17
+
18
+ from huggingface_hub import (
19
+ HfApi,
20
+ batch_bucket_files,
21
+ create_bucket,
22
+ delete_bucket,
23
+ download_bucket_files,
24
+ list_bucket_tree,
25
+ )
26
+
27
+
28
+ DEFAULT_BUCKET_ID = "ppbio-rabeca/birdnet-validator-permission-spike"
29
+ DIAGNOSTIC_PREFIX = "diagnostics/organization-permission-spike"
30
+
31
+
32
+ def _timestamp() -> str:
33
+ return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
34
+
35
+
36
+ def _authenticated_username() -> str:
37
+ profile = HfApi().whoami(token=True)
38
+ username = str(profile.get("name") or profile.get("fullname") or "").strip()
39
+ if not username:
40
+ raise RuntimeError("The active Hugging Face credential does not contain a username.")
41
+ return username
42
+
43
+
44
+ def _safe_name(value: str) -> str:
45
+ cleaned = re.sub(r"[^A-Za-z0-9_.-]+", "-", value.strip()).strip("-")
46
+ return cleaned or "unknown-user"
47
+
48
+
49
+ def _payload(*, actor: str, action: str, role_label: str) -> bytes:
50
+ return (
51
+ json.dumps(
52
+ {
53
+ "schema_version": 1,
54
+ "diagnostic": "birdnet_validator_org_bucket_permission_spike",
55
+ "actor": actor,
56
+ "action": action,
57
+ "role_label": role_label,
58
+ "recorded_at": datetime.now(timezone.utc).isoformat(),
59
+ "contains_project_data": False,
60
+ },
61
+ indent=2,
62
+ sort_keys=True,
63
+ )
64
+ + "\n"
65
+ ).encode("utf-8")
66
+
67
+
68
+ def _write_marker(bucket_id: str, *, action: str, role_label: str) -> str:
69
+ username = _authenticated_username()
70
+ path = f"{DIAGNOSTIC_PREFIX}/{_safe_name(username)}-{_safe_name(role_label)}-{_timestamp()}.json"
71
+ batch_bucket_files(
72
+ bucket_id,
73
+ add=[(_payload(actor=username, action=action, role_label=role_label), path)],
74
+ token=True,
75
+ )
76
+ print(f"PASS: {username} wrote {path} to private Bucket {bucket_id}.")
77
+ return path
78
+
79
+
80
+ def command_identity(_: argparse.Namespace) -> int:
81
+ username = _authenticated_username()
82
+ print(f"Authenticated Hugging Face account: {username}")
83
+ return 0
84
+
85
+
86
+ def command_create(args: argparse.Namespace) -> int:
87
+ username = _authenticated_username()
88
+ bucket_url = create_bucket(args.bucket_id, private=True, exist_ok=True, token=True)
89
+ print(f"Private test Bucket ready: {bucket_url.bucket_id} (created/confirmed by {username}).")
90
+ _write_marker(args.bucket_id, action="bucket_initialized", role_label="admin")
91
+ return 0
92
+
93
+
94
+ def command_write(args: argparse.Namespace) -> int:
95
+ _write_marker(args.bucket_id, action="permission_write", role_label=args.role_label)
96
+ return 0
97
+
98
+
99
+ def command_read(args: argparse.Namespace) -> int:
100
+ username = _authenticated_username()
101
+ entries = [
102
+ item
103
+ for item in list_bucket_tree(
104
+ args.bucket_id,
105
+ prefix=DIAGNOSTIC_PREFIX,
106
+ recursive=True,
107
+ token=True,
108
+ )
109
+ if getattr(item, "type", "file") == "file"
110
+ ]
111
+ if not entries:
112
+ raise RuntimeError(f"No diagnostic marker was visible in {args.bucket_id}.")
113
+
114
+ latest = sorted(entries, key=lambda item: str(item.path))[-1]
115
+ with TemporaryDirectory(prefix="birdnet-hf-bucket-proof-") as temp_dir:
116
+ destination = Path(temp_dir) / "marker.json"
117
+ download_bucket_files(
118
+ args.bucket_id,
119
+ files=[(str(latest.path), destination)],
120
+ raise_on_missing_files=True,
121
+ token=True,
122
+ )
123
+ payload = json.loads(destination.read_text(encoding="utf-8"))
124
+ print(
125
+ "PASS: "
126
+ f"{username} read {latest.path}; marker actor={payload.get('actor', 'unknown')}, "
127
+ f"role_label={payload.get('role_label', 'unknown')}."
128
+ )
129
+ return 0
130
+
131
+
132
+ def command_list(args: argparse.Namespace) -> int:
133
+ username = _authenticated_username()
134
+ entries = list(
135
+ list_bucket_tree(
136
+ args.bucket_id,
137
+ prefix=DIAGNOSTIC_PREFIX,
138
+ recursive=True,
139
+ token=True,
140
+ )
141
+ )
142
+ print(f"Visible diagnostic entries for {username}: {len(entries)}")
143
+ for item in entries:
144
+ print(f"- {item.path}")
145
+ return 0
146
+
147
+
148
+ def command_delete(args: argparse.Namespace) -> int:
149
+ _authenticated_username()
150
+ if args.confirm_delete != args.bucket_id:
151
+ raise RuntimeError(
152
+ "Deletion refused. Pass --confirm-delete with the exact Bucket id to remove only the test Bucket."
153
+ )
154
+ delete_bucket(args.bucket_id, missing_ok=True, token=True)
155
+ print(f"Deleted test Bucket: {args.bucket_id}")
156
+ return 0
157
+
158
+
159
+ def build_parser() -> argparse.ArgumentParser:
160
+ parser = argparse.ArgumentParser(
161
+ description="Probe private Hugging Face organization Bucket access with the currently logged-in account."
162
+ )
163
+ parser.add_argument(
164
+ "--bucket-id",
165
+ default=DEFAULT_BUCKET_ID,
166
+ help=f"Private diagnostic Bucket id (default: {DEFAULT_BUCKET_ID}).",
167
+ )
168
+ subparsers = parser.add_subparsers(dest="command", required=True)
169
+
170
+ subparsers.add_parser("identity", help="Show the account supplied by local HF authentication.").set_defaults(
171
+ func=command_identity
172
+ )
173
+ subparsers.add_parser("create", help="Create/confirm the private Bucket and write the admin marker.").set_defaults(
174
+ func=command_create
175
+ )
176
+ write_parser = subparsers.add_parser("write", help="Write one small permission diagnostic marker.")
177
+ write_parser.add_argument(
178
+ "--role-label",
179
+ required=True,
180
+ choices=["admin", "contributor", "write", "oauth-admin", "oauth-validator"],
181
+ help="Role under test, recorded in the marker only.",
182
+ )
183
+ write_parser.set_defaults(func=command_write)
184
+ subparsers.add_parser("read", help="Read the latest visible diagnostic marker.").set_defaults(func=command_read)
185
+ subparsers.add_parser("list", help="List visible diagnostic markers.").set_defaults(func=command_list)
186
+ delete_parser = subparsers.add_parser("delete", help="Delete the diagnostic Bucket after testing.")
187
+ delete_parser.add_argument("--confirm-delete", required=True)
188
+ delete_parser.set_defaults(func=command_delete)
189
+ return parser
190
+
191
+
192
+ def main() -> int:
193
+ args = build_parser().parse_args()
194
+ try:
195
+ return int(args.func(args))
196
+ except Exception as exc:
197
+ print(f"FAIL: {exc}", file=sys.stderr)
198
+ return 1
199
+
200
+
201
+ if __name__ == "__main__":
202
+ raise SystemExit(main())