Skip to content

Commit 4f12fd9

Browse files
Piotr Brzyskimeta-codesync[bot]
Piotr Brzyski
authored and
meta-codesync[bot]
committed
{Documentation} Add documentation for Project Aria Login
Summary: Adds end user's documentation for [Project Aria Login](https://pypi.org/project/projectaria-login/) module. Reviewed By: kongchen1992 Differential Revision: D109692111 fbshipit-source-id: 1170d45ec0fa0a4792982976b5604996b9259b32
1 parent 4227c9d commit 4f12fd9

16 files changed

Lines changed: 628 additions & 9 deletions

File tree

‎website/docs-ark/aria_studio/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Aria Studio",
3-
"position": 3
3+
"position": 6
44
}

‎website/docs-ark/client-sdk/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Client SDK",
3-
"position": 3
3+
"position": 4
44
}

‎website/docs-ark/mps/_category_.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"label": "Machine Perception Services",
3-
"position": 4
3+
"position": 5
44
}

‎website/docs-ark/projectaria-login/_category_.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Project Aria Login",
3+
"position": 3
4+
}

‎website/docs-ark/projectaria-login/changelog.mdx‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
sidebar_position: 90
3+
title: Changelog
4+
---
5+
6+
# Changelog
7+
8+
---
9+
## Version 0.2.0
10+
*August 2026*
11+
12+
- **Public facade:** Introduced `ProjectAriaLogin` as the single public entry point, exported from the top-level package. It owns the full token lifecycle behind the verbs `login`, `resume`, `logout`, and `adopt_token`, and drives all user interaction (MMA instructions, password entry, encrypted-file passphrase) through async UI callbacks. The CLI was rewritten onto the facade.
13+
- **Internal API boundary:** The low-level auth/token/storage classes (`AuthenticationManager`, `TokenManager`, the MMA and legacy authenticators, and the encrypted-storage store) now live in a private `projectaria_login.login._internal` subpackage. Only the `ProjectAriaLogin` facade and its result, config, and callback types are public — import everything from the top-level `projectaria_login` package.
14+
- **Encrypted file fallback:** When the system keyring is unavailable (headless servers, containers, CI/CD, minimal OS images), the login token is now persisted to an encrypted local file at `~/.projectaria/auth_token.enc`, encrypted with AES-256-GCM using a key derived from the `PROJECTARIA_TOKEN_KEY` environment variable or an interactive passphrase. Removed the legacy plaintext file storage conversion.
15+
- **Passphrase attempt limit:** Interactive passphrase entry now gives up after a fixed number of attempts (and on non-interactive EOF) instead of looping forever, leaving the token unsaved with a clear message rather than hanging.
16+
- **Reusable login API:** Exposed `register_commands()` and `run_command()` so other CLIs can mount the `login`/`verify`/`logout` subcommands without duplicating parser definitions. The auth flows now return a success/failure result that maps to the process exit code.
17+
- **Shared commons package:** Extracted the generic configuration, async HTTP, and GraphQL helpers into a new `projectaria-commons` package (now an automatically-installed runtime dependency) so other Project Aria tools can reuse them without depending on the full login library.
18+
19+
---
20+
## Version 0.1.0
21+
*June 2026*
22+
23+
- **Initial release:** Standalone `projectaria_login` authentication library, extracted and refactored from the MPS CLI so other Aria tools can authenticate users without depending on the full MPS CLI. Includes the login library, a CLI wrapper, unit tests, Buck build targets, and a Python wheel build script.
24+
- **Configurable retries:** Added a config class that controls GraphQL request retry behavior.
25+
- **Integration features:** Added a `save_token` option across the authentication flow, exposed `HttpHelper` as a property on `RequestHelper`, and exposed login URLs and docs as constants for easier integration with applications.
26+
- Relicensed project files under Apache License 2.0.

‎website/docs-ark/projectaria-login/cli-usage.mdx‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
---
2+
sidebar_position: 3
3+
title: CLI Usage
4+
---
5+
6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
9+
# CLI Usage
10+
11+
The `projectaria_login` command provides login, verify, and logout for shell scripts, CI setups, and manual terminal use. It shares credentials with Aria Studio and MPS CLI via the system keyring, with an encrypted-file fallback when the keyring is unavailable.
12+
13+
## Synopsis
14+
15+
```bash
16+
projectaria_login [-v | --verbose] <command> [options]
17+
projectaria_login login --username <username-or-email>
18+
projectaria_login verify
19+
projectaria_login logout
20+
```
21+
22+
## Login
23+
24+
The CLI auto-detects login method based on username. No flag needed to choose MMA vs password.
25+
26+
:::note Already logged in
27+
If a valid token already exists (in the keyring or the encrypted file), `login` short-circuits before any password/MMA prompt and prints `Already logged in as <alias>`. To explicitly check login status, use the [`verify`](#verify) subcommand instead. To force a fresh login, run `projectaria_login logout` first.
28+
:::
29+
30+
### Password Login (tfbnw.net / wptst.com distributed accounts)
31+
32+
For distributed accounts ending in `tfbnw.net` or `*.wptst.com`. For `tfbnw.net` accounts you may omit the domain suffix — it is appended automatically. `*.wptst.com` accounts are **not** auto-completed, so you must pass the full email (e.g. `--username myuser@sub.wptst.com`); running `login --username myuser` for a wptst account would resolve to `myuser@tfbnw.net` and fail.
33+
34+
```bash
35+
projectaria_login login --username myuser
36+
# or
37+
projectaria_login login --username myuser@tfbnw.net
38+
# wptst accounts require the full domain
39+
projectaria_login login --username myuser@sub.wptst.com
40+
```
41+
42+
You will be prompted securely for password (input hidden, no echo):
43+
44+
```
45+
Password:
46+
Successfully logged in as myuser
47+
Your login token has been saved for future use.
48+
```
49+
50+
If the token could not be persisted (no keyring and no usable encryption key), the login still succeeds but prints a warning instead:
51+
52+
```
53+
Password:
54+
Successfully logged in as myuser
55+
Warning: the token could not be saved. You will need to log in again next time.
56+
```
57+
58+
### MMA Login (Managed Meta Accounts)
59+
60+
For Meta Work accounts (email like `user@company.com` or `@meta.com`). Detected automatically when `has_mma_account` returns a UID.
61+
62+
```bash
63+
projectaria_login login --username user@meta.com
64+
```
65+
66+
Output:
67+
68+
```
69+
To log in, visit: https://work.meta.com/cli
70+
Enter the code: ABCD-EFGH
71+
72+
Waiting for authorization...
73+
Successfully logged in as user
74+
Your login token has been saved for future use.
75+
```
76+
77+
**Steps:**
78+
79+
1. CLI prints verification URL and user code. Open URL in browser (automatically uses device flow, no password typed in terminal).
80+
2. Log in with Meta Work SSO in browser, enter code when prompted.
81+
3. CLI polls every 5 seconds until you authorize, or until the device code expires (about 5 minutes) — see the timeout note below.
82+
4. On success, token validated and saved.
83+
84+
:::note Timeout
85+
Authorization must complete within about **5 minutes**. After that the device code expires and you must re-run `projectaria_login login` to get a new code.
86+
:::
87+
88+
### Verbose Logging
89+
90+
Add `-v` or `--verbose` to see debug logs: HTTP requests, keyring operations, token validation steps, and encrypted-file fallback messages.
91+
92+
```bash
93+
projectaria_login -v login --username myuser
94+
```
95+
96+
Log levels:
97+
98+
* default: WARNING and above — only errors and key actions printed
99+
* `-v`: DEBUG — full HTTP helper traces, keyring load/save attempts, GraphQL responses (tokens redacted)
100+
101+
## Encrypted File Fallback
102+
103+
When the system keyring is unavailable (headless servers, containers, CI/CD, minimal OS images), the token is stored in an encrypted local file at `~/.projectaria/auth_token.enc` instead. The file is encrypted with AES-256-GCM using a key derived (via PBKDF2-HMAC-SHA256) from one of:
104+
105+
* **`PROJECTARIA_TOKEN_KEY` environment variable** — recommended for automation. When set, it is used automatically for both saving and loading, with no prompt.
106+
* **An interactive passphrase** — when the keyring is unavailable and no env var is set, the CLI prompts for an encryption passphrase at login and prompts again to decrypt the file when you run `verify` or `logout` (up to 3 attempts each).
107+
108+
The key material must be at least **12 characters**; shorter material is rejected and the token is not saved. At login you get up to **3 attempts** to enter a valid, matching passphrase; if none succeeds, the token is left unsaved and you will need to log in again next time.
109+
110+
```bash
111+
# Automation: no prompt, key comes from the environment
112+
export PROJECTARIA_TOKEN_KEY="a-strong-secret-passphrase"
113+
projectaria_login login --username myuser
114+
```
115+
116+
Example interactive login when the keyring is unavailable:
117+
118+
```
119+
System keyring is unavailable, so the login token will be stored in an encrypted file at /home/user/.projectaria/auth_token.enc.
120+
Tip: set the PROJECTARIA_TOKEN_KEY environment variable to avoid this prompt in automated environments.
121+
The token is encrypted with AES-256-GCM; anyone with the passphrase and file access can decrypt it.
122+
The passphrase must be at least 12 characters.
123+
124+
Encryption passphrase:
125+
Confirm passphrase:
126+
Successfully logged in as myuser
127+
Your login token has been saved for future use.
128+
```
129+
130+
In a non-interactive session with neither a `PROJECTARIA_TOKEN_KEY` nor a passphrase available, the token is not saved (a warning is logged) and you will need to log in again next time. See [Token Storage](/ark/projectaria-login/token-storage#encrypted-file-fallback) for the full security model.
131+
132+
## Verify
133+
134+
Check whether a valid stored token exists without logging in again:
135+
136+
```bash
137+
projectaria_login verify
138+
```
139+
140+
It loads the token from the keyring or the encrypted file, validates it via `query_me`, and reports the result. If the encrypted file is passphrase-protected, it prompts for the passphrase and allows up to **3 attempts**. A wrong (but long-enough) passphrase leaves the file in place so you can retry; even after all 3 attempts fail the file is **kept**, so you can try again later with the correct passphrase. The file is removed only when it is structurally unusable (a malformed blob, an unsupported format, or a payload that decrypts but is not a valid token).
141+
142+
```
143+
Token is valid. Logged in as myuser
144+
```
145+
146+
If no valid token is found it prints `No valid token found. Please log in.` and exits with code `1`.
147+
148+
## Logout
149+
150+
```bash
151+
projectaria_login logout
152+
```
153+
154+
Performs:
155+
156+
1. Loads the token from the keyring, or from the encrypted file (prompting for the passphrase if it is passphrase-protected)
157+
2. POST to `https://graph.oculus.com/logout` to invalidate the server-side session — best effort, continues on failure
158+
3. Deletes the keyring entry `projectaria_tools / session_auth_token`
159+
4. Deletes the encrypted file `~/.projectaria/auth_token.enc` if present
160+
5. Clears in-memory state
161+
162+
Server-side invalidation requires a usable token, so the outcome depends on what could be loaded:
163+
164+
| Situation | Message | Exit code |
165+
|---|---|---|
166+
| A valid token was found, invalidated server-side, and local state cleared | `Successfully logged out.` | 0 |
167+
| Local credentials cleared, but the server-side logout request failed (e.g. a network or HTTP error) | `Local credentials were cleared, but the server-side logout request failed. Your session may still be active; if so, sign out from your account settings.` | 0 |
168+
| No usable stored token — nothing stored, or a stored token that could not be loaded/decrypted (any unusable file is then removed) | `No valid stored token was available to invalidate server-side. The session may still be active, sign out from your account settings to close it.` | 0 |
169+
| A passphrase-protected file could not be decrypted (wrong passphrase, retries exhausted, or no passphrase available) — the file is kept and server-side logout is skipped | `Could not decrypt the stored token, so the encrypted file was kept and server-side logout was skipped. Retry with the correct passphrase, or delete ~/.projectaria/auth_token.enc to remove it.` | 1 |
170+
171+
Output on the common path:
172+
173+
```
174+
Successfully logged out.
175+
```
176+
177+
After a successful logout, Aria Studio and MPS CLI will prompt for login on next use because the shared keyring entry is gone.
178+
179+
## Exit Codes
180+
181+
| Code | Meaning |
182+
|---|---|
183+
| 0 | Success. For `logout` this includes the cases where local credentials were cleared even if the server-side POST failed or no usable token was found. |
184+
| 1 | Any command failure: login failed or was cancelled, `verify` found no valid token, `logout` could not decrypt a passphrase-protected file (so it was kept and server-side logout was skipped), or no command specified |
185+
| 2 | Invalid or missing command-line arguments (argparse usage error) |
186+
187+
## Examples
188+
189+
**Check current login status** — run `verify`: it validates the stored token and reports whether you are logged in, without prompting for a fresh login.
190+
191+
```bash
192+
projectaria_login verify
193+
# Token is valid. Logged in as myuser
194+
```
195+
196+
**Force re-login** by logging out first:
197+
198+
```bash
199+
projectaria_login logout
200+
projectaria_login login --username myuser
201+
```
202+
203+
**Use in scripts**: the CLI always prompts for the password via `getpass` for security, so it cannot accept a non-interactive password. Set `PROJECTARIA_TOKEN_KEY` and log in once interactively, then reuse the stored token in later non-interactive runs.
204+
205+
## Next Steps
206+
207+
* [Token Storage](/ark/projectaria-login/token-storage) to understand keyring backends and the encrypted-file fallback

‎website/docs-ark/projectaria-login/installation.mdx‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
sidebar_position: 2
3+
title: Installation
4+
---
5+
6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
9+
# Installation
10+
11+
## PyPI Install (Recommended)
12+
13+
`projectaria_login` is published to PyPI as `projectaria-login`. Install it in a virtual environment:
14+
15+
<Tabs groupId="operating-systems">
16+
<TabItem value="unix" label="Linux & macOS">
17+
18+
```bash
19+
python3 -m venv ~/projectaria_gen2_python_env
20+
source ~/projectaria_gen2_python_env/bin/activate
21+
python3 -m pip install --upgrade pip
22+
python3 -m pip install projectaria-login
23+
```
24+
25+
</TabItem>
26+
<TabItem value="windows" label="Windows">
27+
28+
```powershell
29+
python -m venv $env:USERPROFILE\projectaria_gen2_python_env
30+
& $env:USERPROFILE\projectaria_gen2_python_env\Scripts\Activate.ps1
31+
python -m pip install --upgrade pip
32+
python -m pip install projectaria-login
33+
```
34+
35+
</TabItem>
36+
</Tabs>
37+
38+
Verify installation:
39+
40+
```bash
41+
projectaria_login --help
42+
```
43+
44+
Expected output shows `login`, `verify`, and `logout` subcommands.
45+
46+
## Keyring Prerequisites
47+
48+
`projectaria_login` stores tokens securely in your operating system's credential manager. No additional system packages are required on macOS or Windows.
49+
50+
:::note Prerequisite for keyring token storage on Linux
51+
52+
On Linux, secure token storage needs a Secret Service provider:
53+
54+
| Distro | Package to install |
55+
|---|---|
56+
| Ubuntu / Debian | `sudo apt install gnome-keyring` (or, for KWallet users, `sudo apt install kwalletmanager`) |
57+
| Fedora | `sudo dnf install gnome-keyring` |
58+
59+
:::
60+
61+
Start the keyring daemon once per session if running headless:
62+
63+
```bash
64+
eval $(gnome-keyring-daemon --start)
65+
```
66+
67+
## Supported Platforms
68+
69+
| OS | Keyring Backend | Python |
70+
|---|---|---|
71+
| macOS 14+ Apple Silicon | macOS Keychain | 3.9 – 3.12 |
72+
| Linux x64 Ubuntu 22.04/24.04, Fedora 40/41 | Secret Service / GNOME Keyring / KWallet | 3.9 – 3.12 |
73+
| Windows x64 | Windows Credential Manager | 3.9 – 3.12 |
74+
75+
## Next Steps
76+
77+
* [CLI Usage](/ark/projectaria-login/cli-usage) — log in and out from terminal

‎website/docs-ark/projectaria-login/start.mdx‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
sidebar_position: 1
3+
title: Overview
4+
---
5+
6+
import Tabs from '@theme/Tabs';
7+
import TabItem from '@theme/TabItem';
8+
9+
# Project Aria Login — Overview
10+
11+
`projectaria_login` is a standalone authentication library for Project Aria tools. It was extracted from the `aria_mps_cli` package to allow other Aria tools — such as Aria Studio, MPS CLI, and custom scripts — to authenticate users without depending on the full MPS CLI.
12+
13+
The library provides both **password-based login** for distributed accounts (`tfbnw.net` / `*.wptst.com`) and **MMA (Managed Meta Account) device-flow login** for Meta Work accounts, with secure token storage via the system keyring and an encrypted-file fallback when no keyring is available.
14+
15+
The PyPI package is published as [`projectaria-login`](https://pypi.org/project/projectaria-login/).
16+
17+
## Key Features
18+
19+
* **Two login methods, auto-detected**: password for `tfbnw.net` / `*.wptst.com` distributed accounts, MMA device flow for Work accounts.
20+
* **Secure storage**: tokens saved to OS keyring under service name `projectaria_tools`, shared with MPS CLI and Aria Studio.
21+
* **Encrypted-file fallback**: when the keyring is unavailable, the token is persisted to an encrypted local file (`~/.projectaria/auth_token.enc`, AES-256-GCM with a PBKDF2-derived key) using either the `PROJECTARIA_TOKEN_KEY` environment variable or an interactive passphrase.
22+
* **Async Python API**: built on `aiohttp`, fully typed with `# pyre-strict`.
23+
* **CLI included**: `projectaria_login login`, `projectaria_login verify`, and `projectaria_login logout` for shell scripts and manual use.
24+
25+
## When to Use It
26+
27+
| Use case | Recommended surface |
28+
|---|---|
29+
| Log in once from terminal before running MPS CLI or Aria Studio | CLI: `projectaria_login login --username ...` |
30+
| Automate authentication in Python scripts, notebooks, or services | Python API: the `ProjectAriaLogin` facade |
31+
| Share credentials across tools on same machine | Keyring storage — automatic, no extra code |
32+
| Build a custom Aria tool needing Project Aria auth | Depend on `projectaria-login` PyPI package, not on `aria_mps_cli` |
33+
34+
## Token Lifecycle
35+
36+
1. **Login**: run the CLI or call `ProjectAriaLogin.login(username)`. The right login method is auto-detected and your session is stored securely.
37+
2. **Resume**: on later runs, `ProjectAriaLogin.resume()` restores your saved session so you don't have to log in again. Expired sessions are cleared automatically.
38+
3. **Share**: Aria Studio, MPS CLI, and `projectaria_login` share the same stored credentials, so logging in once enables all tools.
39+
4. **Logout**: `ProjectAriaLogin.logout()` signs you out and clears your saved session.
40+
41+
## Next Steps
42+
43+
* [Installation](/ark/projectaria-login/installation) — install from PyPI
44+
* [CLI Usage](/ark/projectaria-login/cli-usage) — login, verify, logout, verbose logging
45+
* [Token Storage](/ark/projectaria-login/token-storage) — keyring backends, encrypted-file fallback, shared credentials
46+
* [Troubleshooting](/ark/support/projectaria_login) — common errors and solutions

0 commit comments

Comments
 (0)