@carrierllc/mcp 0.13.29 → 0.13.31

package/README.md

@@ -21,12 +21,183 @@ carrier status          # plugin + MCP + next steps
 carrier plugin install  # zero-cred MCP URL; OAuth on first use in Claude
 carrier open signup     # create account
 carrier examples        # paste-ready “talk to fleet” prompts
-carrier ask "fleet health"   # natural-language fallback; needs CARRIER_API_KEY=ak_…
+carrier login               # browser once; native OAuth refreshes silently
+carrier ask "fleet health"   # uses CLI OAuth / compatible Claude Code OAuth / explicit key
+carrier exec -- bash        # real child terminal with CARRIER_API_KEY in its environment
 ```
 
 **Entry A:** register `https://mcp.carrier.llc/mcp` with no token. The first tool
 call in Claude/Cursor opens Clerk OAuth (Google / GitHub / email).
 
+### Natural-language answers
+
+`carrier ask "how many subscribers are there?"` and the interactive home's
+**Ask the fleet** action present executed tool results as readable answers.
+Known OCS list summaries use the server's authoritative `summary.total`, not a
+recount of the displayed rows. That number describes the result/page, not
+necessarily the entire fleet; paging, missing rows and shortened display are
+reported explicitly. Nested subscriber status and SIM inventory status remain
+separate. A server facet that could not read nested status is not a claim that
+subscriber status is missing.
+
+This is deterministic presentation, not another AI/model call. The original
+question distinguishes counts from requested lists/status/details. Unsupported
+predictions and judgements receive an explicit limitation rather than unrelated
+records. Current subscriber status uses the shared OCS open-period normalizer,
+with its maintained closed-history fallback; SIM inventory remains separate.
+
+Default JSON presentation uses typed scalar allowlists and explicit shallow
+account/result wrappers. Unknown fields, nested shapes, and wrong field types
+are omitted with a safe limitation; they are never recursively dumped. Safe
+ordinary scalar facts remain readable. Empty or unsupported summary facets are
+omitted. Plain-text tool answers are passed through, shortened only at whole
+sentence/row boundaries; this is not a general redaction guarantee for arbitrary
+prose. Oversized indivisible rows are omitted entirely with the raw-output hint.
+
+```bash
+carrier ask "how many subscribers are there?" --json
+```
+
+`--json` is explicit raw access: complete JSON stdout, no banner/spinner; plain
+text is encoded as a JSON string. Raw output may contain sensitive data. Failures
+remain nonzero with errors on stderr. The MCP machine contract and domain
+commands are unchanged. Ambiguous intents and confirmation-required mutations
+still do not execute a resolved tool.
+
+### OAuth and terminal handoff
+
+Carrier commands, status and Ask the Fleet share credential resolution. Explicit
+`CARRIER_API_KEY` / `CARRIER_ORG_API_KEY` always win. Native `carrier login` stores
+a private refreshable session with one cross-process owner lock and atomic writes.
+Login, refresh and logout serialize; a completed logout cannot be resurrected by
+an earlier refresh. A crashed CLI owner leaves a fail-closed `credentials.lock`
+directory: verify that no CLI login/refresh is running before manually removing
+that directory. Changing the callback port triggers fresh client registration.
+Native login and refresh request the exact production MCP resource. A present
+wrong/malformed token-response resource is rejected before credential storage;
+legacy absence is distinct and refresh retains a previously known binding.
+
+### Existing bash/zsh terminal (explicit setup)
+
+```bash
+source "$(carrier shell-path bash)" # use zsh instead of bash in zsh
+carrier_auth_export
+# CARRIER_API_KEY is now exported in THIS shell and its subsequent children.
+# Before an arbitrary headless job, refresh this snapshot again:
+carrier_auth_export && your-headless-job
+carrier logout
+carrier_auth_clear                 # erase this shell's snapshot too
+```
+
+Only a shipped static file is sourced. No secret is printed, evaluated as code,
+put in command arguments/history, or written to a startup file. The function
+reads an anonymous private pipe via an inherited descriptor. It refuses shell
+traps and turns off xtrace/verbose **without restoring them**, because the next
+caller command could expand the newly exported environment. Bash opt-in loading
+enables errtrace so caller ERR traps are visible for refusal. Trusted commands,
+same-UID process environment readers and crash dumps can still expose a bearer;
+this is not protection from a compromised shell/OS. Do not re-enable tracing
+around credentials.
+
+Shell acceptance requires **both bash and zsh**: `pnpm test:oauth-shell`.
+`CARRIER_TEST_ZSH` may point to an isolated zsh binary and
+`CARRIER_TEST_ZSH_MODULE_PATH` to its matching modules. The general repair suite
+reports a missing zsh interpreter as an explicit SKIP, never a zsh pass; the
+acceptance command fails when either interpreter is unavailable.
+
+OAuth exports carry `CARRIER_OAUTH_ORIGIN`, `CARRIER_OAUTH_EXPIRES_AT` (epoch ms)
+and a `CARRIER_OAUTH_HANDOFF` fingerprint plus non-secret `CARRIER_OAUTH_BINDING`.
+Carrier invocations reread only the selected owner, source directory/file, server,
+registration and opaque subject/grant. Same-owner token rotation is allowed;
+expiry, logout, owner/config/account/org changes fail closed, never switch to
+another valid client session. Old exports without binding must be exported again.
+These metadata equality checks are not cryptographic account/org proof.
+Arbitrary programs retain it until expiry: re-run `carrier_auth_export` before
+consumption. Replacing `CARRIER_API_KEY` intentionally overrides the fingerprint
+and remains authoritative. `carrier_auth_clear` removes this shell's exported
+key and metadata, not the other client's login.
+
+`carrier exec -- <command> [args...]` remains available for a trusted child only;
+no setup required, no parent-shell mutation, and child exit/signal is preserved.
+OAuth is a short-lived bearer, **not** an `ak_` key.
+
+### Supported read-only MCP owners
+
+Without a native session, a current compatible MCP access token may be reused;
+no refresh grant is copied, rotated or written by Carrier. If the owner expires,
+refresh it in that client or use native `carrier login`. No owner reauth command
+is invoked. Multiple current owners require `CARRIER_MCP_OAUTH_OWNER=hermes` or
+`claude`; the CLI never guesses which account to use.
+
+- **Claude Code 2.1.277 and 2.1.296:** exact inspected config and storage adapters.
+  The owner's `.claude.json` lives under `CLAUDE_CONFIG_DIR || ~`; an existing
+  legacy `.config.json` takes precedence. For the consuming CLI's cwd, local
+  `projects[real git root || real cwd].mcpServers` wins over approved ancestor
+  `.mcp.json` project config, which wins over user config. Other projects are not
+  candidates. Project import supports explicit trusted user settings approval
+  only; pending/rejected or ambiguous policy/settings fail closed.
+  Hashes the actual `{type,url,headers:headers||{}}` in original insertion order:
+  HTTP, SSE and absent `type` remain distinct. No hardcoded empty-header hash.
+  Managed selection remains unsupported and fails closed; no inferred
+  plugin/proxy/CLI override resolution. Authorization/API-key/cookie headers and
+  unresolved environment substitutions are not imported as OAuth.
+  `CLAUDE_SECURESTORAGE_CONFIG_DIR` takes precedence by presence for credential
+  storage; present-empty selects `~/.claude`, while nonempty and `CLAUDE_CONFIG_DIR`
+  retain the exact NFC strings (no trim or resolve before the Keychain hash).
+  `USER || os.userInfo().username` selects the exact account, with Claude's
+  invalid-account fallback. An approved custom OAuth environment selects only
+  its own suffix; unrelated suffixes/accounts are never enumerated.
+  Linux reads the private `.credentials.json`. `CARRIER_MCP_OAUTH_FILE` explicitly
+  selects that file backend on either platform, without consulting Keychain.
+  CamelCase expiry is epoch milliseconds.
+- **Hermes:** selected `HERMES_HOME` (default `~/.hermes`), exact configured
+  `mcp_servers.carrier.url`, with private `mcp-tokens/carrier.json`,
+  `.client.json` and `.meta.json`. Real snake_case access-token fields,
+  `hermes_issuer`, Bearer type and absolute `expires_at` in seconds are required.
+  Issuer/discovery endpoints, client registration and resource configuration are
+  checked. Legacy relative-only expiry is refused. Config JSON and simple scalar
+  block YAML are supported; nested/alias/flow constructs fail closed.
+
+`CARRIER_MCP_OAUTH_SERVER` selects an alternative explicit name. Private mode
+and current-user file ownership, exact issuer/resource, `read` scope and finite
+future expiry are required. `CARRIER_OAUTH_ACCOUNT` optionally selects the
+Carrier opaque token's user prefix; it is **not** cryptographic account/org
+proof. Only the server validates actual token audience, organization and grant
+permissions. Invalid native state never falls through to another owner.
+
+On macOS the packaged `native/claude-keychain.js` uses the built-in JXA
+Objective-C bridge and Apple Security Framework: one generic-password query,
+exact service and account, `kSecMatchLimitOne`, `kSecReturnData`,
+`kSecUseAuthenticationUIFail`, plus process-local legacy UI inhibition.
+There is no compiler/download/install-at-login dependency, no `security -w`,
+no broad dump, and no owner lock/refresh/login. Only non-secret selectors reach
+stdin. Only the selected access-token fields reach an inherited private FD;
+stdout/stderr are discarded. Owner refresh grants, client secrets and unrelated
+credentials never leave the helper. Apple may report an ACL prompt requirement
+or locked store identically (`errSecInteractionNotAllowed`): `locked` denotes
+that noninteractive refusal, not a diagnosis of the physical Keychain state.
+`errSecAuthFailed`/user-cancel are `denied`, parse errors are `malformed`, and
+other failures are `unavailable`. None falls back to plaintext or Hermes.
+Only `errSecItemNotFound` for the exact item permits Claude's documented private
+file fallback. An existing item without the exact MCP entry does not fall back.
+Keychain reuse requires `claude --version` to be exactly 2.1.277 or 2.1.296;
+other versions fail closed. Compatibility is an explicit inspected allowlist,
+not a version range. The source contracts are tested on Linux; a real Darwin
+absent-item probe also executes the packaged helper byte-for-byte without
+stdout/stderr. Successful existing-item access and installed end-to-end Mac
+OAuth remain unproved. The inspected Mac 2.1.296 query returned `denied`
+(OSStatus -25293), not absence; this adapter never broadens Keychain access or
+falls back after that refusal.
+Claude Desktop, Cursor, Windsurf and mcp-remote remain unsupported owners.
+Issuer-less entries are intentionally rejected. `carrier logout` disables MCP
+reuse until a successful native login and never edits the owner's store or
+another shell's explicit keys.
+
+Native API references: [Apple SecItemCopyMatching](https://developer.apple.com/documentation/security/secitemcopymatching(_:_:)),
+[Apple SecItem.h](https://github.com/apple-oss-distributions/Security/blob/main/keychain/headers/SecItem.h),
+[Apple JXA release notes](https://developer.apple.com/library/archive/releasenotes/InterapplicationCommunication/RN-JavaScriptForAutomation/),
+[Claude authentication storage](https://code.claude.com/docs/en/authentication).
+
 ### Domain commands
 
 With a headless key in the environment, each capability has its own command,

package/dist/{chunk-LJPYVILK.js → chunk-EHJEAI4V.js}

@@ -1855,16 +1855,22 @@ function storefrontScreen(input) {
 // package.json
 var package_default = {
   name: "@carrierllc/mcp",
-  version: "0.13.29",
+  version: "0.13.31",
   description: "Carrier MCP \u2014 natural-language control of MVNO/eSIM fleets via eSIMVault OCS. Stdio mode for direct integration with Claude Desktop, Cursor, Windsurf, and MCP-compatible clients. Ships the `carrier` CLI (plugin install + white-label eSIM storefront scaffold).",
   license: "MIT",
   author: "Carrier (Lifecycle Innovations Limited)",
   homepage: "https://mcp.carrier.llc",
   type: "module",
+  carrierCompatibility: {
+    claudeOAuthOwnerVersion: "2.1.277",
+    claudeOAuthOwnerVersions: ["2.1.277", "2.1.296"]
+  },
   main: "./dist/index.js",
   files: [
     "dist",
     "plugin",
+    "shell",
+    "native",
     "README.md",
     "templates",
     "!templates/**/node_modules",
@@ -1882,7 +1888,9 @@ var package_default = {
     lint: "eslint src",
     prepublishOnly: "pnpm run build",
     "build:test": "tsup --config tsup.test.config.ts",
-    test: "pnpm run build && pnpm run build:test && node --test test/*.test.js",
+    test: "pnpm run build && pnpm run build:test && node --test-concurrency=1 --test test/*.test.js && pnpm run test:oauth-repair",
+    "test:oauth-repair": "node --experimental-transform-types --test-concurrency=1 --test test/oauth-repair.test.mjs test/claude-owner.test.mjs test/current-owner.test.mjs",
+    "test:oauth-shell": "node scripts/check-oauth-shell.mjs",
     "check:pack": "node scripts/check-pack-size.mjs",
     "generate:domains": "node scripts/generate-domains.mjs"
   },
@@ -4344,6 +4352,32 @@ function ocsArray(data, keys) {
   }
   return [];
 }
+function subscriberIccid(row) {
+  if (row === null || typeof row !== "object") return "";
+  const r = row;
+  const imsiList = r.imsiList;
+  if (Array.isArray(imsiList)) {
+    for (const entry of imsiList) {
+      if (entry && typeof entry === "object") {
+        const v = entry.iccid;
+        if (typeof v === "string" && v.length > 0) return v;
+        if (typeof v === "number") return String(v);
+      }
+    }
+  }
+  for (const key of ["iccid", "ICCID"]) {
+    const v = r[key];
+    if (typeof v === "string" && v.length > 0) return v;
+    if (typeof v === "number") return String(v);
+  }
+  const sim = r.sim;
+  if (sim && typeof sim === "object") {
+    const v = sim.iccid;
+    if (typeof v === "string" && v.length > 0) return v;
+    if (typeof v === "number") return String(v);
+  }
+  return "";
+}
 var FACET_TALLY_MAX = 25;
 var OCS_LIST_FACETS = {
   templates: [
@@ -5418,6 +5452,8 @@ export {
   recordToolDescription,
   buildRouterCatalog,
   ROUTER_RULES,
+  OCS_LIST_KEYS,
+  subscriberIccid,
   withOcsListSummary,
   extractDailyUsage,
   daysUntil,
@@ -5480,6 +5516,7 @@ export {
   walletScreen,
   greenzoneScreen,
   storefrontScreen,
+  package_default,
   CARRIER_VERSION
 };
-//# sourceMappingURL=chunk-LJPYVILK.js.map
+//# sourceMappingURL=chunk-EHJEAI4V.js.map