@tiangong-lca/cli 0.1.2 → 0.1.5

package/README.md

@@ -13,27 +13,33 @@ whenToUpdate:
   - when user-facing command examples change
 checkPaths:
   - README.md
+  - .env.example
   - package.json
   - pnpm-workspace.yaml
   - pnpm-lock.yaml
   - bin/**
   - src/cli.ts
   - src/main.ts
+  - src/auth-identity-receipt.ts
   - src/batch.ts
   - src/command-spec.ts
   - src/lib/auth-identity-receipt.ts
+  - src/lib/oauth-loopback.ts
+  - src/lib/oauth-pkce.ts
+  - src/lib/supabase-session.ts
   - src/lib/lca-release.ts
   - scripts/run-auth-identity-production-case.ts
   - test/auth-identity*.test.ts
+  - test/public-auth-identity-receipt.test.ts
   - test/lca-release*.test.ts
-lastReviewedAt: 2026-08-26
-lastReviewedCommit: b9a99011fcc1d7388355e66649113ac5d4a7a9c8
-lastReviewedNote: 'Reviewed for Issue #237: identifies 0.1.2 as the release-only package identity for the bounded pnpm 11.24 public API while runtime, exports, dependencies, and release behavior stay fixed.'
+lastReviewedAt: 2026-08-31
+lastReviewedCommit: 352c11c5ffafaea1bf94133be92f3337b847866a
+lastReviewedNote: 'Reviewed for Issue #252: identifies 0.1.5 as the replacement OAuth release after unpublished 0.1.4, preserving exports, dependencies, and release behavior.'
 ---
 
 # TianGong LCA CLI
 
-Package: `@tiangong-lca/cli` Executable: `tiangong-lca` Current package version: `0.1.2` Node: `24.19.0`
+Package: `@tiangong-lca/cli` Executable: `tiangong-lca` Current package version: `0.1.5` Node: `24.19.0`
 
 Repository development is single-track on pnpm `11.24.0` and TypeScript `7.0.2`. The published package remains a clean, package-manager-neutral consumer artifact: it contains runtime files only, not pnpm, TypeScript, Oxlint, tests, source-only tooling, or repository lockfiles.
 
@@ -53,6 +59,18 @@ Review note, 2026-08-26: Issue #236 changes only the repository and clean-consum
 
 Review note, 2026-08-26: Issue #237 releases the already reviewed bounded CommandSpec/batch runtime and pnpm 11.24 toolchain as `@tiangong-lca/cli@0.1.2`. The release changes only package metadata and four live CLI-version fixtures; runtime files, public subpaths and object identities, dependencies, the sole lock, Node 24.19.0, TypeScript 7.0.2, package-manager-neutral consumers, and automated provenance path remain unchanged.
 
+Review note, 2026-08-29: Issue #240 adds the typed `@tiangong-lca/cli/auth-identity-receipt` public parser entry without changing package version 0.1.2 or auth behavior. It directly re-exports the existing strict parser, schema/timeout constants, and receipt types; the remote runner and test internals stay private, and the previous `dist/src/lib/**` deep path remains blocked.
+
+Review note, 2026-08-29: Issue #242 releases that public parser as `@tiangong-lca/cli@0.1.3`. Only package identity and four existing exact-version fixtures change; `./batch`, `./command-spec`, `./auth-identity-receipt`, the executable, dependencies, pnpm lock, Node 24.19.0 / TypeScript 7.0.2 toolchain, and package-manager-neutral consumer contract are otherwise unchanged.
+
+Review note, 2026-08-31: Issue #244 adds Supabase OAuth 2.1 Authorization Code + S256 PKCE without adding a dependency or changing package version/exports. `auth login` uses a registered public client, exact literal-`127.0.0.1` callback, state validation, and shell-free system browser; it atomically stores rotating access/refresh tokens in a private session file. `auth status` performs no network request and reveals no credential or session path; `auth whoami` and `auth doctor-auth` use the live redacted identity receipt. `auth logout` deletes only that matching local session; Connected applications owns grant revocation. `TIANGONG_LCA_ACCESS_TOKEN` is a short-lived, online-verified, memory-only headless option. The reversible API key remains only as a transition fallback and is never used by OAuth mode.
+
+Review note, 2026-08-31: Issue #247 prevents a second CLI process from failing when the first process removes `session.json.lock` between contention and metadata read. Only an absent lock is treated as released; permission, I/O, malformed-owner, timeout, and stale-owner safety behavior is unchanged.
+
+Review note, 2026-08-31: Issue #246 releases that OAuth runtime as `@tiangong-lca/cli@0.1.4`. Only package identity and four existing exact-version fixtures change; the executable and public subpaths, dependencies, pnpm lock, Node 24.19.0 / TypeScript 7.0.2 toolchain, auth behavior, and package-manager-neutral consumer contract are otherwise unchanged.
+
+Review note, 2026-08-31: Issue #252 replaces the stopped-unpublished 0.1.4 attempt with `@tiangong-lca/cli@0.1.5` after platform-complete session coverage merged. Only package identity, four version fixtures, and release evidence change; executable/public subpaths, OAuth behavior, dependencies, pnpm lock, Node/TypeScript toolchain, and consumer contract stay unchanged.
+
 Review note, 2026-07-12: `dataset maintenance plan/apply/verify` provides current-user RLS-scoped exact-row maintenance with immutable plans, explicit approval, per-action logs, platform audit correlation, and independent readback. `merge-support-aliases` now runs only in `target_mode=owner_draft`: source/target support and all changed rows stay private `state_code=0`; publication is a separate future workflow.
 
 Review note, 2026-07-13: maintenance scans now prove exact-count pagination even when PostgREST returns fewer rows than the requested `--page-size`. An incomplete or inconsistent scan fails before artifacts, approval, or mutation; under stable filtered membership/order the proof represents a complete ordered multi-request traversal, not one transaction-level/MVCC snapshot.
@@ -108,11 +126,12 @@ node ./bin/tiangong-lca.js --help
 
 The package exposes only these supported module APIs in addition to the executable launcher subpath:
 
+- `@tiangong-lca/cli/auth-identity-receipt` parses the exact safe receipt projection offline and exports its schema, Node-safe timeout ceiling, and receipt types. It does not expose session resolution, network execution, or test internals; callers that need a fresh receipt still invoke the CLI command.
 - `@tiangong-lca/cli/command-spec` parses, creates, artifact-binds, and executes exact `tiangong-foundry.command-spec.v1` objects. `display` is diagnostic only; executable plus argv and binding bytes/SHA-256 form the canonical authority. Sync and async execution always use `shell:false`; async callers may inject resolver, clock, sleep, spawn, timeout, and abort adapters. `timeoutMs` must fit Node's maximum timer delay.
 - `@tiangong-lca/cli/batch` runs bounded generic work with an overall run contract and a required per-item `{ item_id, content_sha256, policy_sha256 }` contract. Every identity/content/policy/resource projection is validated before work starts and rechecked before resumed acceptance or a fresh claim. Identity changes or getter failures emit `item_identity_drift` with `BatchItemIdentityDriftError`, execute zero attempts, and do not let the batch return before other in-flight items drain. An escaping scheduler/event/stop callback records the first infrastructure error, closes further claims, awaits all worker settlements, then rejects. Input order, truthful resource-aware claim order, completion order, pause/stop behavior, awaited monotonic events, and exception isolation are explicit. Optional exclusive keys serialize only matching resources; a blocked key remains unclaimed and consumes no worker while later free keys may use the public ceiling of 64 workers. Per-resource FIFO queues expose only their head through an ordered binary min-heap, giving near `O(n log k)` ready scheduling for `k` resources.
 - Mutation batches reject automatic retry. A consumed or ambiguous mutation can continue only through an explicitly supplied readback-recovery callback; resume requires exact run and item contracts, and each resumed or rejected result participates in stop decisions before fresh claims. Retry/backoff values must be non-negative safe integers within Node's timer limit. Exclusive keys must be runtime strings. `withBatchRunLock` gives one canonical run directory one cross-process lock domain, permits reentrancy only from a still-live scope owned by the current holder, keeps the top-level promise pending until detached nested scopes drain, rejects completed-context reentry into a later owner, preserves live or foreign-host locks, and stale-recovers only a same-host dead PID. Public lock callers cannot set PID, host, or ownership time; timeout/poll values are non-negative safe integers within Node's timer limit.
 
-The packed ESM, CJS dynamic-import, and TypeScript consumers exercise both public subpaths and generated declarations. Deep imports and `import '@tiangong-lca/cli'` remain unsupported.
+The packed ESM, CJS dynamic-import, and TypeScript consumers exercise every public subpath and generated declaration. Deep imports and `import '@tiangong-lca/cli'` remain unsupported.
 
 ## Env
 
@@ -120,25 +139,45 @@ Remote commands require:
 
 ```bash
 TIANGONG_LCA_API_BASE_URL=
-TIANGONG_LCA_API_KEY=
 TIANGONG_LCA_SUPABASE_PUBLISHABLE_KEY=
+TIANGONG_LCA_OAUTH_CLIENT_ID=
 TIANGONG_LCA_REGION=us-east-1
 ```
 
 Notes:
 
 - `TIANGONG_LCA_API_BASE_URL` accepts the project root, `/functions/v1`, or `/rest/v1`.
-- `TIANGONG_LCA_API_KEY` is the TianGong user API key from the account page, not a Supabase project key.
-- The CLI exchanges `TIANGONG_LCA_API_KEY` for a user session, then reuses the access token for both Edge Functions and direct Supabase access.
+- `TIANGONG_LCA_OAUTH_CLIENT_ID` is the environment-specific registered public CLI client; it is not a secret.
+- Run `tiangong-lca auth login` once in a trusted terminal. All Edge Function and direct Supabase commands then reuse the OAuth access token and rotate the refresh token on demand.
+- For approved headless execution, set `TIANGONG_LCA_AUTH_MODE=access-token` and inject one short-lived `TIANGONG_LCA_ACCESS_TOKEN`. It is verified online, kept only in process memory, and never refreshed.
+- Transition-only compatibility uses `TIANGONG_LCA_AUTH_MODE=legacy-user-api-key` plus `TIANGONG_LCA_API_KEY`. OAuth failures never fall back to this password-equivalent credential.
 
 Optional session control:
 
 ```bash
+TIANGONG_LCA_AUTH_MODE=oauth
+TIANGONG_LCA_OAUTH_REDIRECT_URI=http://127.0.0.1:49191/oauth/callback
 TIANGONG_LCA_SESSION_FILE=
 TIANGONG_LCA_DISABLE_SESSION_CACHE=false
 TIANGONG_LCA_FORCE_REAUTH=false
 ```
 
+## OAuth Session Commands
+
+```text
+tiangong-lca auth login
+tiangong-lca auth status --json
+tiangong-lca auth whoami --json
+tiangong-lca auth doctor-auth --json
+tiangong-lca auth logout
+```
+
+The callback URI must exactly match the URI registered with the selected Supabase OAuth client. The default is `http://127.0.0.1:49191/oauth/callback`; OAuth client redirect URIs do not support wildcards. Login never accepts a username, password, authorization code, access token, refresh token, or PKCE verifier through argv. On POSIX, the app directory is `0700` and `session.json` is `0600`; writes and refresh-token rotation use a temporary file, atomic rename, and the existing cross-process state lock. Windows callers must keep the selected parent ACL current-user-only because chmod bits are not an ACL.
+
+`auth status` is intentionally local-only and non-mutating. It reports whether a matching session can be used or refreshed, but sets `onlineVerified: false`; it never prints email, tokens, a session path, or a credential fingerprint. `auth whoami` performs the live redacted identity receipt. `auth doctor-auth` first checks local readiness, then performs that live check; a missing OAuth session returns `login-required` so a human can run `auth login`. An AI agent must never ask for or handle the user's password, authorization code, access token, or refresh token.
+
+Local logout does not revoke the server grant. To invalidate every refresh token for the CLI client, open Account → Connected applications and disconnect TianGong CLI.
+
 ## Auth Identity Receipt
 
 Use the identity receipt before a production-backed case or any later owner-draft write gate:
@@ -147,7 +186,7 @@ Use the identity receipt before a production-backed case or any later owner-draf
 tiangong-lca auth identity-receipt --expected-project-ref <project-ref> --expected-user-id <user-id> --json
 ```
 
-The command performs no dataset write. It exchanges the normal user API key for a session, checks the canonical Supabase project, and makes a bounded live `GET /auth/v1/user`. A cached token that receives `401` or `403` may be refreshed and retried exactly once; all other transport or response failures are terminal. A valid production guard requires:
+The command performs no dataset write. It resolves the selected OAuth, explicit headless, or transition-only legacy session, checks the canonical Supabase project, and makes a bounded live `GET /auth/v1/user`. A refreshable cached token that receives `401` or `403` may be refreshed and retried exactly once; an explicit headless access token is never refreshed. All other transport or response failures are terminal. A valid production guard requires:
 
 - `schema` exactly `tiangong-lca.auth-identity-receipt.v1`;
 - `status: "passed"`, `operation: "current-user-read"`, and `remote_write_mode: "read-only"`;
@@ -162,7 +201,7 @@ For the explicitly authorized local production read case from a validated reposi
 pnpm case:auth-identity:production -- --env-file <data-foundry-ignored-.env> --expected-project-ref <project-ref> --expected-user-id <user-id> --out-dir <new-private-case-directory>
 ```
 
-The runner reads only `TIANGONG_LCA_API_BASE_URL`, `TIANGONG_LCA_SUPABASE_PUBLISHABLE_KEY`, and `TIANGONG_LCA_TEST_API_KEY`; the last is mapped to the child process's standard API-key variable. It does not accept an alternate CLI path. The pnpm command first performs a clean TS7 build without the production env. Its plain-Node runner then single-reads source/config/lock and the freshly generated `dist/src/**/*.js`, hashes the source tree, runner, runtime, exact entrypoint, and pnpm lock, and copies those exact built buffers into a private snapshot before exposing the key. It forces reauthentication with session cache disabled, runs only the built snapshot from an exclusively created clean directory with an argv array and `shell:false`, cleans the snapshot before publishing success artifacts, and persists only the parsed receipt and case manifest. POSIX creates the case directory as `0700` and files as `0600`; Windows inherits ACLs from the caller-selected parent, so use a user-restricted parent because mode bits are not an ACL guarantee. The runner never stores raw child stdout/stderr and is intentionally not wired to CI secrets. This receipt is locally hash-verifiable, not server-signed attestation.
+The historical production-case runner remains a transition-only legacy fixture: it reads only `TIANGONG_LCA_API_BASE_URL`, `TIANGONG_LCA_SUPABASE_PUBLISHABLE_KEY`, and `TIANGONG_LCA_TEST_API_KEY`; the last is mapped to the child process's explicit legacy variable. It does not accept an alternate CLI path. The pnpm command first performs a clean TS7 build without the production env. Its plain-Node runner then single-reads source/config/lock and the freshly generated `dist/src/**/*.js`, hashes the source tree, runner, runtime, exact entrypoint, and pnpm lock, and copies those exact built buffers into a private snapshot before exposing the key. It forces reauthentication with session cache disabled, runs only the built snapshot from an exclusively created clean directory with an argv array and `shell:false`, cleans the snapshot before publishing success artifacts, and persists only the parsed receipt and case manifest. POSIX creates the case directory as `0700` and files as `0600`; Windows inherits ACLs from the caller-selected parent, so use a user-restricted parent because mode bits are not an ACL guarantee. The runner never stores raw child stdout/stderr and is intentionally not wired to CI secrets. New automation should use OAuth/headless mode instead. This receipt is locally hash-verifiable, not server-signed attestation.
 
 ## LCI/LCIA Data Release
 
@@ -228,7 +267,7 @@ tiangong-lca release status --release-run-id <release-run-id> --json
 }
 ```
 
-The CLI verifies every local upload against its declared byte size, SHA-256, media type, and required pair before requesting signed URLs. Upload receipts and downloads are written atomically with private file permissions. Existing outputs are preserved unless `--force` is explicit. The publish credential fingerprint is derived locally from `TIANGONG_LCA_API_KEY`; callers cannot inject it through the request file.
+The CLI verifies every local upload against its declared byte size, SHA-256, media type, and required pair before requesting signed URLs. Upload receipts and downloads are written atomically with private file permissions. Existing outputs are preserved unless `--force` is explicit. Release requests use the resolved actor access token and `client_id`-aware database policy; no credential-derived fingerprint is accepted from local state or the request file.
 
 Calculation results and published artifacts remain file-first:
 
@@ -318,7 +357,7 @@ Key outputs under `--out-dir`:
 - `outputs/identity-candidates.jsonl`
 - `outputs/identity-candidate-sources.json`
 
-`--candidate-input` is repeatable and accepts JSON, JSONL, or a directory scanned recursively for JSON/JSONL candidate rows. Embedded `candidates` from the request and local-scan candidates are evaluated together. Add `--remote-candidates` when the preflight should also call `process_hybrid_search` or `flow_hybrid_search`; `--remote-query` overrides the target-derived search text and `--remote-limit` caps returned candidate rows. Remote candidate search uses the normal Supabase session env: `TIANGONG_LCA_API_BASE_URL`, `TIANGONG_LCA_API_KEY`, `TIANGONG_LCA_SUPABASE_PUBLISHABLE_KEY`, and optional `TIANGONG_LCA_REGION`.
+`--candidate-input` is repeatable and accepts JSON, JSONL, or a directory scanned recursively for JSON/JSONL candidate rows. Embedded `candidates` from the request and local-scan candidates are evaluated together. Add `--remote-candidates` when the preflight should also call `process_hybrid_search` or `flow_hybrid_search`; `--remote-query` overrides the target-derived search text and `--remote-limit` caps returned candidate rows. Remote candidate search uses the normal OAuth session env above and optional `TIANGONG_LCA_REGION`.
 
 When remote search is enabled, the CLI sends a compact fielded `query` string plus supported edge-search options to `process_hybrid_search` or `flow_hybrid_search`: `filter`, `match_count`, `page_size`, `data_source`, `match_threshold`, `lexical_weight`, `semantic_weight`, and `rrf_k`. `lexical_weight` controls the single database-owned `extracted_md` lexical branch. Request-level `remote_candidate_search.profile_hints` are not sent to the Edge Function. They are applied locally before scoring candidates so Foundry can provide source-derived facts such as flow type, flow property, reference unit, elementary categories, geography, reference-flow names, technology route, and system boundary without polluting the full-text/semantic query.
 

package/dist/src/auth-identity-receipt.d.ts

@@ -0,0 +1,2 @@
+export { AUTH_IDENTITY_MAX_TIMEOUT_MS, AUTH_IDENTITY_RECEIPT_SCHEMA, parseAuthIdentityReceipt, } from './lib/auth-identity-receipt.js';
+export type { AuthIdentityReceipt, AuthIdentityReceiptScope } from './lib/auth-identity-receipt.js';

package/dist/src/auth-identity-receipt.js

@@ -0,0 +1,2 @@
+export { AUTH_IDENTITY_MAX_TIMEOUT_MS, AUTH_IDENTITY_RECEIPT_SCHEMA, parseAuthIdentityReceipt, } from './lib/auth-identity-receipt.js';
+//# sourceMappingURL=auth-identity-receipt.js.map

package/dist/src/auth-identity-receipt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-identity-receipt.js","sourceRoot":"","sources":["../../src/auth-identity-receipt.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,4BAA4B,EAC5B,4BAA4B,EAC5B,wBAAwB,GACzB,MAAM,gCAAgC,CAAC","sourcesContent":["export {\n  AUTH_IDENTITY_MAX_TIMEOUT_MS,\n  AUTH_IDENTITY_RECEIPT_SCHEMA,\n  parseAuthIdentityReceipt,\n} from './lib/auth-identity-receipt.js';\nexport type { AuthIdentityReceipt, AuthIdentityReceiptScope } from './lib/auth-identity-receipt.js';\n"]}

package/dist/src/cli.d.ts

@@ -1,5 +1,6 @@
 import type { DotEnvLoadResult } from './lib/dotenv.js';
 import type { FetchLike } from './lib/http.js';
+import { inspectSupabaseAuthStatus, loginWithSupabaseOAuth, logoutSupabaseUserSession } from './lib/supabase-session.js';
 import { type AuthIdentityReceipt, type RunAuthIdentityReceiptOptions } from './lib/auth-identity-receipt.js';
 import { type LifecyclemodelAutoBuildReport, type RunLifecyclemodelAutoBuildOptions } from './lib/lifecyclemodel-auto-build.js';
 import { type LifecyclemodelResultingProcessReport, type RunLifecyclemodelResultingProcessOptions } from './lib/lifecyclemodel-resulting-process.js';
@@ -71,6 +72,9 @@ export type CliDeps = {
     dotEnvStatus: DotEnvLoadResult;
     fetchImpl: FetchLike;
     runAuthIdentityReceiptImpl?: (options: RunAuthIdentityReceiptOptions) => Promise<AuthIdentityReceipt>;
+    loginWithSupabaseOAuthImpl?: typeof loginWithSupabaseOAuth;
+    logoutSupabaseUserSessionImpl?: typeof logoutSupabaseUserSession;
+    inspectSupabaseAuthStatusImpl?: typeof inspectSupabaseAuthStatus;
     runPublishImpl?: (options: RunPublishOptions) => Promise<PublishReport>;
     runValidationImpl?: (options: RunValidationOptions) => Promise<ValidationRunReport>;
     runLcaReleaseImpl?: (options: RunLcaReleaseOptions) => Promise<LcaReleaseReport>;

package/dist/src/cli.js

@@ -3,6 +3,9 @@ import { buildDoctorReport, readRuntimeEnv } from './lib/env.js';
 import { CliError, toErrorPayload } from './lib/errors.js';
 import { stringifyJson } from './lib/io.js';
 import { loadCliPackageVersion } from './lib/package-version.js';
+import { requireSupabaseRestRuntime } from './lib/supabase-client.js';
+import { inspectSupabaseAuthStatus, loginWithSupabaseOAuth, logoutSupabaseUserSession, } from './lib/supabase-session.js';
+import { OAUTH_LOGIN_TIMEOUT_MAX_MS } from './lib/oauth-loopback.js';
 import { AUTH_IDENTITY_MAX_TIMEOUT_MS, AUTH_IDENTITY_RECEIPT_SCHEMA, runAuthIdentityReceipt, } from './lib/auth-identity-receipt.js';
 import { runLifecyclemodelAutoBuild, } from './lib/lifecyclemodel-auto-build.js';
 import { runLifecyclemodelBuildResultingProcess, } from './lib/lifecyclemodel-resulting-process.js';
@@ -87,7 +90,7 @@ Usage:
 Commands:
 Implemented Commands:
   doctor     show environment diagnostics
-  auth       identity-receipt
+  auth       login | status | whoami | doctor-auth | logout | identity-receipt
   search     flow | process | lifecyclemodel
   process    get | list | identity-preflight | build-plan | scope-statistics | dedup-review | auto-build | resume-build | publish-build | complete-required-fields | save-draft | batch-build | refresh-references | verify-rows
   dataset    contract get | context-pack | classification children/path/audit/apply | curation-queue build/next/verify | import-lca convert | author | patch apply | save-draft | source upload-attachments | validate | verify-remote | bilingual extract/apply/validate | evidence-search plan/run | references rewrite/refresh-remote | maintenance clear-account/plan/apply/verify/flow-identity
@@ -100,13 +103,17 @@ Implemented Commands:
   admin      embedding-run
 
 Planned Surface (not implemented yet):
-  auth       whoami | doctor-auth
   job        get | wait | logs
 
 Planned commands currently print an explicit "not implemented yet" message and exit with code 2.
 
 Examples:
   tiangong-lca doctor
+  tiangong-lca auth login
+  tiangong-lca auth status --json
+  tiangong-lca auth whoami --json
+  tiangong-lca auth doctor-auth --json
+  tiangong-lca auth logout
   tiangong-lca auth identity-receipt --expected-project-ref <project-ref> --expected-user-id <user-id> --json
   tiangong-lca search flow --input ./request.json
   tiangong-lca search process --input ./request.json --dry-run
@@ -185,15 +192,79 @@ Environment:
 }
 function renderAuthHelp() {
     return `Usage:
-  tiangong-lca auth identity-receipt [options]
+  tiangong-lca auth <login|status|whoami|doctor-auth|logout|identity-receipt> [options]
 
 Implemented Subcommands:
+  login             Authorize the registered public CLI through browser PKCE and store a private rotating session
+  status            Inspect only local auth readiness without reading or printing credentials
+  whoami             Run the live, redacted identity receipt for the current user
+  doctor-auth        Combine local readiness with a live, redacted identity check
+  logout            Remove only this local CLI session; revoke the connected-app grant from the account page
   identity-receipt  Live, read-only proof of the authenticated account and Supabase project
 
-Planned Subcommands:
-  whoami | doctor-auth
+Use "tiangong-lca auth <subcommand> --help" for details.
+`.trim();
+}
+function renderAuthStatusHelp() {
+    return `Usage:
+  tiangong-lca auth status [--json]
+
+Inspects only the matching local session metadata. It performs no network request, never refreshes
+a token, and never emits email, token, session path, or credential fingerprint. A ready result can
+still be remotely revoked; use "auth doctor-auth" when live verification is required. If OAuth login
+is required, hand the terminal to the human user and run "tiangong-lca auth login". Never ask an AI
+agent to collect a username, password, authorization code, access token, or refresh token.
+`.trim();
+}
+function renderAuthWhoamiHelp() {
+    return `Usage:
+  tiangong-lca auth whoami [--timeout-ms <n>] [--json]
+
+Runs the same live, read-only and redacted proof as "auth identity-receipt" without requiring an
+expected identity assertion. It may refresh an OAuth session under the private session lock. Output
+contains no token, full email address, session path, or credential fingerprint.
+`.trim();
+}
+function renderAuthDoctorHelp() {
+    return `Usage:
+  tiangong-lca auth doctor-auth [--timeout-ms <n>] [--json]
+
+First checks local readiness without network access. If ready, it performs the live redacted identity
+receipt. Missing OAuth authorization returns login-required without attempting password bootstrap.
+Run "tiangong-lca auth login" only in a trusted human-controlled terminal.
+`.trim();
+}
+function renderAuthLoginHelp() {
+    return `Usage:
+  tiangong-lca auth login [options]
+
+Options:
+  --timeout-ms <n>  Browser callback timeout 1..${OAUTH_LOGIN_TIMEOUT_MAX_MS} ms (default: 180000)
+  --json            Print compact JSON; default output is pretty JSON
+  -h, --help
+
+Required env:
+  TIANGONG_LCA_API_BASE_URL
+  TIANGONG_LCA_SUPABASE_PUBLISHABLE_KEY
+  TIANGONG_LCA_OAUTH_CLIENT_ID
+
+Optional env:
+  TIANGONG_LCA_AUTH_MODE=oauth
+  TIANGONG_LCA_OAUTH_REDIRECT_URI (default: exact registered 127.0.0.1 callback)
+  TIANGONG_LCA_SESSION_FILE
+
+The CLI binds only 127.0.0.1, opens the system browser without a shell, verifies state and S256
+PKCE, and atomically writes access/rotating refresh tokens to a private session file. It never
+accepts a username, password, authorization code, access token, or refresh token as an argv value.
+`.trim();
+}
+function renderAuthLogoutHelp() {
+    return `Usage:
+  tiangong-lca auth logout [--json]
 
-Use "tiangong-lca auth identity-receipt --help" for the machine-receipt contract.
+Removes only the locally cached session bound to the current project/client. To revoke the OAuth
+grant and every refresh token, disconnect TianGong CLI from Connected applications in the account
+page. An explicit TIANGONG_LCA_ACCESS_TOKEN is never persisted and therefore has nothing to delete.
 `.trim();
 }
 function renderAuthIdentityReceiptHelp() {
@@ -218,8 +289,14 @@ Safety:
 
 Required env:
   TIANGONG_LCA_API_BASE_URL
-  TIANGONG_LCA_API_KEY
   TIANGONG_LCA_SUPABASE_PUBLISHABLE_KEY
+  TIANGONG_LCA_OAUTH_CLIENT_ID and a prior "tiangong-lca auth login"
+
+Headless alternative:
+  TIANGONG_LCA_ACCESS_TOKEN (short-lived actor token; never cached or refreshed)
+
+Legacy compatibility:
+  TIANGONG_LCA_AUTH_MODE=legacy-user-api-key plus TIANGONG_LCA_API_KEY
 
 Optional session env:
   TIANGONG_LCA_SESSION_FILE
@@ -2369,6 +2446,99 @@ function parseAuthIdentityReceiptFlags(args) {
         timeoutMs,
     };
 }
+function parseAuthLoginFlags(args) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            tokens: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                'timeout-ms': { type: 'string' },
+            },
+        });
+    }
+    catch (error) {
+        throw new CliError(String(error), { code: 'INVALID_ARGS', exitCode: 2 });
+    }
+    const timeoutOccurrences = parsed.tokens.filter((entry) => entry.kind === 'option' && entry.name === 'timeout-ms').length;
+    if (timeoutOccurrences > 1) {
+        throw new CliError('Option --timeout-ms may be provided only once.', {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
+    const timeoutText = parsed.values['timeout-ms'];
+    const timeoutMs = typeof timeoutText === 'string' ? Number(timeoutText) : 180_000;
+    if (!Number.isSafeInteger(timeoutMs) ||
+        timeoutMs <= 0 ||
+        timeoutMs > OAUTH_LOGIN_TIMEOUT_MAX_MS) {
+        throw new CliError(`Expected --timeout-ms to be an integer between 1 and ${OAUTH_LOGIN_TIMEOUT_MAX_MS}.`, { code: 'INVALID_TIMEOUT', exitCode: 2 });
+    }
+    return {
+        help: Boolean(parsed.values.help),
+        json: Boolean(parsed.values.json),
+        timeoutMs,
+    };
+}
+function parseAuthLogoutFlags(args) {
+    try {
+        const { values } = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+            },
+        });
+        return { help: Boolean(values.help), json: Boolean(values.json) };
+    }
+    catch (error) {
+        throw new CliError(String(error), { code: 'INVALID_ARGS', exitCode: 2 });
+    }
+}
+function parseAuthLiveFlags(args) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            tokens: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                'timeout-ms': { type: 'string' },
+            },
+        });
+    }
+    catch (error) {
+        throw new CliError(String(error), { code: 'INVALID_ARGS', exitCode: 2 });
+    }
+    const timeoutOccurrences = parsed.tokens.filter((entry) => entry.kind === 'option' && entry.name === 'timeout-ms').length;
+    if (timeoutOccurrences > 1) {
+        throw new CliError('Option --timeout-ms may be provided only once.', {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
+    const timeoutText = parsed.values['timeout-ms'];
+    const timeoutMs = typeof timeoutText === 'string' ? Number(timeoutText) : 10_000;
+    if (!Number.isSafeInteger(timeoutMs) ||
+        timeoutMs <= 0 ||
+        timeoutMs > AUTH_IDENTITY_MAX_TIMEOUT_MS) {
+        throw new CliError(`Expected --timeout-ms to be an integer between 1 and ${AUTH_IDENTITY_MAX_TIMEOUT_MS}.`, { code: 'INVALID_TIMEOUT', exitCode: 2 });
+    }
+    return {
+        help: Boolean(parsed.values.help),
+        json: Boolean(parsed.values.json),
+        timeoutMs,
+    };
+}
 function parseRemoteFlags(args) {
     let values;
     try {
@@ -5543,6 +5713,9 @@ export async function executeCli(argv, deps) {
     try {
         const { flags, command, subcommand, commandArgs } = parseCommandLine(argv);
         const authIdentityReceiptImpl = deps.runAuthIdentityReceiptImpl ?? runAuthIdentityReceipt;
+        const oauthLoginImpl = deps.loginWithSupabaseOAuthImpl ?? loginWithSupabaseOAuth;
+        const oauthLogoutImpl = deps.logoutSupabaseUserSessionImpl ?? logoutSupabaseUserSession;
+        const authStatusImpl = deps.inspectSupabaseAuthStatusImpl ?? inspectSupabaseAuthStatus;
         const publishImpl = deps.runPublishImpl ?? runPublish;
         const validationImpl = deps.runValidationImpl ?? runValidation;
         const lcaReleaseImpl = deps.runLcaReleaseImpl ?? runLcaRelease;
@@ -5671,6 +5844,90 @@ export async function executeCli(argv, deps) {
                 stderr: '',
             };
         }
+        if (command === 'auth' && subcommand === 'status') {
+            const authFlags = parseAuthLogoutFlags(commandArgs);
+            if (authFlags.help) {
+                return { exitCode: 0, stdout: `${renderAuthStatusHelp()}\n`, stderr: '' };
+            }
+            const receipt = authStatusImpl({ runtime: requireSupabaseRestRuntime(deps.env) });
+            return {
+                exitCode: receipt.status === 'ready' ? 0 : 1,
+                stdout: stringifyJson(receipt, authFlags.json),
+                stderr: '',
+            };
+        }
+        if (command === 'auth' && subcommand === 'whoami') {
+            const authFlags = parseAuthLiveFlags(commandArgs);
+            if (authFlags.help) {
+                return { exitCode: 0, stdout: `${renderAuthWhoamiHelp()}\n`, stderr: '' };
+            }
+            const receipt = await authIdentityReceiptImpl({
+                env: deps.env,
+                fetchImpl: deps.fetchImpl,
+                cliVersion: loadCliPackageVersion(import.meta.url),
+                expectedProjectRef: null,
+                expectedUserId: null,
+                timeoutMs: authFlags.timeoutMs,
+            });
+            return { exitCode: 0, stdout: stringifyJson(receipt, authFlags.json), stderr: '' };
+        }
+        if (command === 'auth' && subcommand === 'doctor-auth') {
+            const authFlags = parseAuthLiveFlags(commandArgs);
+            if (authFlags.help) {
+                return { exitCode: 0, stdout: `${renderAuthDoctorHelp()}\n`, stderr: '' };
+            }
+            const local = authStatusImpl({ runtime: requireSupabaseRestRuntime(deps.env) });
+            if (local.status !== 'ready') {
+                return {
+                    exitCode: 1,
+                    stdout: stringifyJson({
+                        schemaVersion: 'tiangong.cli-auth-doctor.v1',
+                        status: 'login-required',
+                        local,
+                        live: null,
+                    }, authFlags.json),
+                    stderr: '',
+                };
+            }
+            const live = await authIdentityReceiptImpl({
+                env: deps.env,
+                fetchImpl: deps.fetchImpl,
+                cliVersion: loadCliPackageVersion(import.meta.url),
+                expectedProjectRef: null,
+                expectedUserId: null,
+                timeoutMs: authFlags.timeoutMs,
+            });
+            return {
+                exitCode: 0,
+                stdout: stringifyJson({
+                    schemaVersion: 'tiangong.cli-auth-doctor.v1',
+                    status: 'passed',
+                    local,
+                    live,
+                }, authFlags.json),
+                stderr: '',
+            };
+        }
+        if (command === 'auth' && subcommand === 'login') {
+            const authFlags = parseAuthLoginFlags(commandArgs);
+            if (authFlags.help) {
+                return { exitCode: 0, stdout: `${renderAuthLoginHelp()}\n`, stderr: '' };
+            }
+            const receipt = await oauthLoginImpl({
+                runtime: requireSupabaseRestRuntime(deps.env),
+                fetchImpl: deps.fetchImpl,
+                loginTimeoutMs: authFlags.timeoutMs,
+            });
+            return { exitCode: 0, stdout: stringifyJson(receipt, authFlags.json), stderr: '' };
+        }
+        if (command === 'auth' && subcommand === 'logout') {
+            const authFlags = parseAuthLogoutFlags(commandArgs);
+            if (authFlags.help) {
+                return { exitCode: 0, stdout: `${renderAuthLogoutHelp()}\n`, stderr: '' };
+            }
+            const receipt = await oauthLogoutImpl({ runtime: requireSupabaseRestRuntime(deps.env) });
+            return { exitCode: 0, stdout: stringifyJson(receipt, authFlags.json), stderr: '' };
+        }
         if (command === 'search' && !subcommand && commandArgs.includes('--help')) {
             return { exitCode: 0, stdout: `${renderSearchHelp()}\n`, stderr: '' };
         }