@tiangong-lca/cli 0.1.0 → 0.1.1

package/README.md

@@ -19,16 +19,19 @@ checkPaths:
   - bin/**
   - src/cli.ts
   - src/main.ts
+  - src/lib/auth-identity-receipt.ts
   - src/lib/lca-release.ts
+  - scripts/run-auth-identity-production-case.ts
+  - test/auth-identity*.test.ts
   - test/lca-release*.test.ts
 lastReviewedAt: 2026-08-25
-lastReviewedCommit: 9078fe123e5909b680f27af1af1d2018bcd02826
-lastReviewedNote: 'Reviewed for Issue #226: the public package guide identifies the 0.1.0 pnpm/TypeScript 7 compatibility release while the tarball remains package-manager neutral.'
+lastReviewedCommit: 47b44c65cf4bf27070fa1057e672c6ef2b2e54f3
+lastReviewedNote: 'Reviewed for Issue #230: identifies 0.1.1 as the public auth-receipt release on exact Node 24.19.0 with cryptographic Sigstore and isolated pnpm verification.'
 ---
 
 # TianGong LCA CLI
 
-Package: `@tiangong-lca/cli` Executable: `tiangong-lca` Current package version: `0.1.0` Node: `24.x`
+Package: `@tiangong-lca/cli` Executable: `tiangong-lca` Current package version: `0.1.1` Node: `24.19.0`
 
 Repository development is single-track on pnpm `11.23.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.
 
@@ -36,6 +39,10 @@ Review note, 2026-08-25: Issue #224 migrates repository development and release
 
 Review note, 2026-08-25: Issue #226 publishes that 0.1.0 compatibility boundary after merged PR #225. Version metadata and public release evidence advance to 0.1.0; the runtime JavaScript/assets surface, command behavior, Node 24 runtime, pnpm/TypeScript 7 development baseline, native pnpm Trusted Publishing/provenance, and exact released-commit workspace handoff remain unchanged from the reviewed feature delivery.
 
+Review note, 2026-08-25: Issue #228 implements `auth identity-receipt` as a bounded read-only current-user proof. It checks expected project intent before session work, verifies the live user through `/auth/v1/user`, allows one auth-refresh replay after 401/403, and emits an exact-key canonical receipt without API keys, tokens, full email addresses, session paths, or credential-derived fingerprints. Production callers must pass both expected assertions and accept only `assertions.mode="intent-bound"`.
+
+Review note, 2026-08-25: Issue #230 publishes the merged identity receipt as `@tiangong-lca/cli@0.1.1`. Runtime logic and published dependencies remain unchanged; the sole pnpm lock changes only for exact dev-only `sigstore@5.0.0`. Local metadata, engines, and every workflow converge on Node 24.19.0. Release automation asserts actual platform/architecture across the reusable four-platform pre-tag matrix and provides `pnpm release:verify-published` for cryptographic Fulcio/CT/Rekor provenance, registry signatures, actual tarball integrity, isolated user/global package-manager configuration, exact pnpm 11.23.0, and credential-free bin/ESM/CJS consumer proof.
+
 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.
@@ -112,6 +119,31 @@ TIANGONG_LCA_DISABLE_SESSION_CACHE=false
 TIANGONG_LCA_FORCE_REAUTH=false
 ```
 
+## Auth Identity Receipt
+
+Use the identity receipt before a production-backed case or any later owner-draft write gate:
+
+```text
+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:
+
+- `schema` exactly `tiangong-lca.auth-identity-receipt.v1`;
+- `status: "passed"`, `operation: "current-user-read"`, and `remote_write_mode: "read-only"`;
+- exact expected project/user values with `assertions.mode: "intent-bound"` and `requested_count: 2`;
+- a fresh capture time and a valid recomputed `receipt_scope_sha256`.
+
+Calling without expectations is allowed for discovery but produces `assertions.mode: "observed"`; it is not an authorization guard. The safe display email is masked and must not be used as the account key. The receipt deliberately excludes credentials, full email, session-file details, raw response metadata, and all credential/token/path-derived fingerprints.
+
+For the explicitly authorized local production read case from a validated repository checkout, invoke the narrow TypeScript runner with a new private output directory:
+
+```text
+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.
+
 ## LCI/LCIA Data Release
 
 The `release` command family is the authenticated transport used by the standalone release control plane. It does not introduce a TIDAS schema variant: result packages reuse the existing Process exchange structure for LCI and the existing Process LCIA result fields, with a LifecycleModel referencing the resulting Process.

package/dist/src/cli.js

@@ -3,6 +3,7 @@ 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 { 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';
 import { runLifecyclemodelPublishResultingProcess, } from './lib/lifecyclemodel-publish-resulting-process.js';
@@ -86,6 +87,7 @@ Usage:
 Commands:
 Implemented Commands:
   doctor     show environment diagnostics
+  auth       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
@@ -105,6 +107,7 @@ Planned commands currently print an explicit "not implemented yet" message and e
 
 Examples:
   tiangong-lca doctor
+  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
   tiangong-lca process get --id <process-id>
@@ -180,6 +183,50 @@ Environment:
   .env loaded: ${dotEnvStatus.loaded ? `yes (${dotEnvStatus.path}, ${dotEnvStatus.count} keys)` : 'no'}
 `.trim();
 }
+function renderAuthHelp() {
+    return `Usage:
+  tiangong-lca auth identity-receipt [options]
+
+Implemented Subcommands:
+  identity-receipt  Live, read-only proof of the authenticated account and Supabase project
+
+Planned Subcommands:
+  whoami | doctor-auth
+
+Use "tiangong-lca auth identity-receipt --help" for the machine-receipt contract.
+`.trim();
+}
+function renderAuthIdentityReceiptHelp() {
+    return `Usage:
+  tiangong-lca auth identity-receipt [options]
+
+Options:
+  --expected-project-ref <ref>  Assert the exact Supabase project before session/network access
+  --expected-user-id <id>       Assert the exact server-verified authenticated user
+  --timeout-ms <n>              Request timeout 1..${AUTH_IDENTITY_MAX_TIMEOUT_MS} ms (default: 10000)
+  --json                        Print compact JSON; default output is pretty JSON
+  -h, --help
+
+Receipt schema:
+  ${AUTH_IDENTITY_RECEIPT_SCHEMA}
+
+Safety:
+  This is a read-only command that performs one live read of /auth/v1/user, with at most one
+  force-refresh retry after a 401 or 403. It never emits API keys, bearer/session
+  tokens, full email addresses, session paths, or credential-derived fingerprints. Production guards
+  must pass both expected assertions and require assertions.mode="intent-bound".
+
+Required env:
+  TIANGONG_LCA_API_BASE_URL
+  TIANGONG_LCA_API_KEY
+  TIANGONG_LCA_SUPABASE_PUBLISHABLE_KEY
+
+Optional session env:
+  TIANGONG_LCA_SESSION_FILE
+  TIANGONG_LCA_DISABLE_SESSION_CACHE
+  TIANGONG_LCA_FORCE_REAUTH
+`.trim();
+}
 function renderDoctorHelp() {
     return `Usage:
   tiangong-lca doctor [--json]
@@ -2269,6 +2316,59 @@ function parseDoctorFlags(args) {
         json: Boolean(values.json),
     };
 }
+function parseAuthIdentityReceiptFlags(args) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            tokens: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                'expected-project-ref': { type: 'string' },
+                'expected-user-id': { type: 'string' },
+                'timeout-ms': { type: 'string' },
+            },
+        });
+    }
+    catch (error) {
+        throw new CliError(String(error), {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
+    const tokens = parsed.tokens;
+    for (const optionName of ['expected-project-ref', 'expected-user-id', 'timeout-ms']) {
+        const occurrences = tokens.filter((entry) => entry.kind === 'option' && entry.name === optionName).length;
+        if (occurrences > 1) {
+            throw new CliError(`Option --${optionName} may be provided only once.`, {
+                code: 'INVALID_ARGS',
+                exitCode: 2,
+            });
+        }
+    }
+    const timeoutText = typeof parsed.values['timeout-ms'] === 'string' ? parsed.values['timeout-ms'] : undefined;
+    const timeoutMs = timeoutText === undefined ? 10_000 : Number(timeoutText);
+    if (!Number.isInteger(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),
+        expectedProjectRef: typeof parsed.values['expected-project-ref'] === 'string'
+            ? parsed.values['expected-project-ref']
+            : null,
+        expectedUserId: typeof parsed.values['expected-user-id'] === 'string'
+            ? parsed.values['expected-user-id']
+            : null,
+        timeoutMs,
+    };
+}
 function parseRemoteFlags(args) {
     let values;
     try {
@@ -5442,6 +5542,7 @@ function applyRemoteOverrides(env, overrides) {
 export async function executeCli(argv, deps) {
     try {
         const { flags, command, subcommand, commandArgs } = parseCommandLine(argv);
+        const authIdentityReceiptImpl = deps.runAuthIdentityReceiptImpl ?? runAuthIdentityReceipt;
         const publishImpl = deps.runPublishImpl ?? runPublish;
         const validationImpl = deps.runValidationImpl ?? runValidation;
         const lcaReleaseImpl = deps.runLcaReleaseImpl ?? runLcaRelease;
@@ -5541,6 +5642,35 @@ export async function executeCli(argv, deps) {
                 stderr: '',
             };
         }
+        if (command === 'auth' && !subcommand) {
+            if (commandArgs.length === 0 ||
+                (commandArgs.length === 1 && ['--help', '-h'].includes(commandArgs[0]))) {
+                return { exitCode: 0, stdout: `${renderAuthHelp()}\n`, stderr: '' };
+            }
+            throw new CliError('The auth namespace accepts only -h or --help.', {
+                code: 'INVALID_ARGS',
+                exitCode: 2,
+            });
+        }
+        if (command === 'auth' && subcommand === 'identity-receipt') {
+            const authFlags = parseAuthIdentityReceiptFlags(commandArgs);
+            if (authFlags.help) {
+                return { exitCode: 0, stdout: `${renderAuthIdentityReceiptHelp()}\n`, stderr: '' };
+            }
+            const receipt = await authIdentityReceiptImpl({
+                env: deps.env,
+                fetchImpl: deps.fetchImpl,
+                cliVersion: loadCliPackageVersion(import.meta.url),
+                expectedProjectRef: authFlags.expectedProjectRef,
+                expectedUserId: authFlags.expectedUserId,
+                timeoutMs: authFlags.timeoutMs,
+            });
+            return {
+                exitCode: 0,
+                stdout: stringifyJson(receipt, authFlags.json),
+                stderr: '',
+            };
+        }
         if (command === 'search' && !subcommand && commandArgs.includes('--help')) {
             return { exitCode: 0, stdout: `${renderSearchHelp()}\n`, stderr: '' };
         }