feat(auth): prepare opaque credential acceptance and growth-safe CLI guidance

.prettierignore

@@ -4,3 +4,6 @@ node_modules/
 package-lock.json
 *.tgz
 .sdk-source/
+
+# Preserve the upstream golden vectors byte-for-byte.
+test/fixtures/machine-credentials-v1.json

README.md

@@ -13,9 +13,51 @@ polymorfa version
 ## Requirements
 
 - Node.js 22 or newer
-- A Polymorfa organization API key or exact-project token for developer requests
+- A Polymorfa team key or exact-project token for developer requests
 - A server API key or short-lived client token for Messaging requests
 
+## Account browser sign-in
+
+The separate `account` commands require an API environment that registers the
+Polymorfa CLI device client. Installing a CLI package does not enable that server
+feature. Supply the trusted API and Console origins for the same environment:
+
+```shell
+polymorfa account login --profile personal \
+  --api-origin https://api.example.invalid \
+  --console-origin https://console.example.invalid
+polymorfa account status --profile personal --json
+polymorfa account teams --profile personal --limit 25 --json
+polymorfa account projects --profile personal --team TEAM_UUID --json
+polymorfa account logout --profile personal --json
+```
+
+Replace the example origins with your configured environment. Login prints the
+validated approval URL and user code to standard error; open that URL and approve
+the request in the browser. It never opens a browser automatically or accepts a
+session token on the command line. `--json` prints one final result to standard
+output. `--timeout` cancels the operation without extending the server's original
+device-code expiry. Interrupting an already redeemed sign-in attempts to revoke
+that new session; an uncertain revocation is reported as uncertain.
+
+Account sessions use their own profile file and operating-system keyring
+namespace. The opaque session stays in the keyring; short-lived verified JWTs
+stay in memory. `account list` and `account use NAME` inspect or select only these
+account profiles. They do not change the active machine profile. API-key,
+project-token and Messaging commands cannot use an account session.
+
+The only account resource commands are the read-only `account teams` and
+`account projects`. Each response is one page; pass `--after` the returned
+`nextAfter` UUID to continue. Current membership and approved live team/project
+grants are checked by the API on every read. Approval for all current and future
+resources does not add command permissions. There is no account raw-request,
+key-minting or messaging command. These commands require the local Node.js CLI
+and are refused by the browser build before reading its environment or fetching.
+
+Logout reports remote session revocation and local profile/keyring cleanup
+separately. Incomplete cleanup or unconfirmed revocation exits unsuccessfully;
+local removal alone is not proof that a remote session was revoked.
+
 ## Development installation
 
 With access to the private source repository, install the current development
@@ -140,7 +182,7 @@ The registry comes from the real command files. Commands needing the installed C
 ## Authentication profiles
 
 Until the backend exposes a revocable CLI device-authorization flow, login
-accepts an organization API key or exact-project token through standard input:
+accepts an team key or exact-project token through standard input:
 
 ```shell
 printf '%s' "$POLYMORFA_API_KEY" | \
@@ -160,6 +202,12 @@ Secret Service. A keyring failure stops the command; the CLI never silently
 falls back to plaintext. `auth status` reports local secure-store availability
 in this development slice and does not yet claim remote identity validation.
 
+Treat all Polymorfa credentials as opaque strings. Pass them unchanged; never
+parse them or assume a fixed length. Credential columns must store at least 512
+characters, preferably unrestricted text. Client-token length varies with its
+bindings, Customer block and signing key ID. Local prefix, encoding and checksum
+checks do not authenticate a credential; the service checks live authority.
+
 Environment credentials take precedence over the active profile for automation.
 An explicit `--profile <name>` takes precedence over environment credentials.
 
@@ -257,7 +305,7 @@ your shell to its startup file if you want completion in later sessions.
 
 ## Inspect sessions
 
-Use an organization API key with `sessions:read` to inspect stored session
+Use an team key with `sessions:read` to inspect stored session
 metadata:
 
 ```shell
@@ -272,7 +320,7 @@ Use a session ID from the list for `view` or `status`; these commands do not
 accept `--project`. `status` reads the stored status and optional reason from
 the session record. It does not probe the device or wait for a connection.
 Key metadata listing and revocation are available through `key list` and
-`key revoke`; the CLI does not mint or rotate organization keys.
+`key revoke`; the CLI does not mint or rotate team keys.
 
 ## QuickLinks
 
@@ -290,7 +338,7 @@ The request accepts `customerId`, `externalId`, and `configuration`. See
 [Guided session creation and configuration](#guided-session-creation-and-configuration)
 for the configuration fields.
 
-Inspect or cancel a link with an organization API key or an exact-project
+Inspect or cancel a link with an team key or an exact-project
 token that has `quicklink:manage`:
 
 ```shell
@@ -493,7 +541,7 @@ header.
 
 ### Flow drafts and provider lifecycle
 
-Flow commands require a project scope and an organization API key or project
+Flow commands require a project scope and an team key or project
 token. Reads use `sessions:read`; mutations use `sessions:manage`.
 
 ```shell
@@ -576,7 +624,7 @@ linked to another project; the API checks that the credential can access it.
 
 ### Official API observations and templates
 
-The `cloud` commands require an organization API key or a project token with the
+The `cloud` commands require an team key or a project token with the
 listed scope. Client tokens cannot use these commands. Server-side feature
 access still applies: an installed command does not enroll a Number or enable a
 beta feature.
@@ -1243,7 +1291,7 @@ sox greeting.wav -t raw -r 16000 -e signed -b 16 -c 1 - | \
 
 Polymorfa checks every call against the team's call policy before the
 destination rings. `calls policy` and `calls opt-outs` read and change that
-policy and require an organization API key (`POLYMORFA_API_KEY` or a profile).
+policy and require an team key (`POLYMORFA_API_KEY` or a profile).
 A project token used as the API key reaches the API, which refuses it with
 `403` (exit code 3). A client token is not a Platform credential, so the CLI
 refuses the command before sending a request (exit code 2).
@@ -1322,9 +1370,9 @@ polymorfa calls check +14155550123 --session support
 ### Call statistics and export
 
 `calls stats` summarizes calls and `calls export` writes call detail records.
-Both accept an organization API key or an exact-project token with the
+Both accept an team key or an exact-project token with the
 `sessions:read` scope. Pass `--project` to read one project. Without it, an
-organization API key reads every project in the organization. A project token
+team key reads every project in the organization. A project token
 reads only its own project and requires `--project`.
 
 ```shell
@@ -1413,7 +1461,7 @@ or times out, the command keeps the password on screen and exits successfully.
 Voice Automation is a beta (`calls.voice-automation`) for enrolled teams only.
 For other teams, every change except delete fails with `voice_not_enabled`.
 Reads, previews and deletes keep working after a team leaves the beta. The
-commands require an organization server API key with `voice:read` (lists,
+commands require an team key with `voice:read` (lists,
 views, previews) or `voice:manage` (changes).
 
 ### Audio library
@@ -1690,7 +1738,7 @@ request metadata.
 
 ## Platform access and security
 
-Organization server API keys can inspect the credential, membership, audit,
+Team keys can inspect the credential, membership, audit,
 ban, incident, saved QuickLink settings, and project-token metadata made
 available by the Platform API:
 
@@ -2253,7 +2301,7 @@ status, and safe counters, never primary credentials, listener credentials,
 forwarding secrets, or unrestricted payloads.
 
 `polymorfa_session_list` is a read-only discovery tool for one explicit project
-UUID. It uses the selected CLI organization API key with `sessions:read` and
+UUID. It uses the selected CLI team key with `sessions:read` and
 returns session ID, name, stored status, and test-mode flag. It omits phone
 numbers, credentials, and message data. The tool does not probe the live device.
 Project tokens and Messaging client tokens cannot use this tool. A failed read
@@ -2465,7 +2513,7 @@ the CLI never creates or confirms a replacement purchase automatically.
 
 ### Number tier changes
 
-Tier changes use an organization API key. Quote first, review the credit charge
+Tier changes use an team key. Quote first, review the credit charge
 and effective time, then confirm that exact quote:
 
 ```shell
@@ -2554,7 +2602,7 @@ polymorfa hybrid-link resume --session NUMBER --expected-revision REVISION
 For project and session routing scopes, `--project`, the nearest linked project,
 and the selected profile determine the project in that order. A project-token
 profile fails when its project differs from the linked directory. Team routing
-scope uses an organization API key and ignores directory project links. `quicklink
+scope uses an team key and ignores directory project links. `quicklink
 availability` shows existing connection status and any QuickLink that can be
 resumed.
 
@@ -2575,7 +2623,7 @@ transports within the restrictions inherited from the team and project.
 
 ### Functions
 
-Functions are project-owned. Select `--project` or use the linked project/profile context. The commands accept an organization API key or a project token; browser client tokens are refused. Access also depends on the team's enabled Functions release and the configured execution region.
+Functions are project-owned. Select `--project` or use the linked project/profile context. The commands accept an team key or a project token; browser client tokens are refused. Access also depends on the team's enabled Functions release and the configured execution region.
 
 ```bash
 polymorfa function list --project PROJECT_UUID
@@ -2660,7 +2708,7 @@ does not retrieve media or webhook deliveries.
 
 ### Spending limits and funding priority
 
-With an organization key carrying `billing:read`, inspect current controls:
+With an team key carrying `billing:read`, inspect current controls:
 
 ```bash
 polymorfa billing limits list --project <project-uuid> --json