{"_id":"u-chan-secrets","_rev":"7-fd6c357a789c726e011d5a94d5090b5b","name":"u-chan-secrets","dist-tags":{"next":"4.0.0","latest":"4.0.0"},"versions":{"0.0.0-stage":{"name":"u-chan-secrets","version":"0.0.0-stage","_id":"u-chan-secrets@0.0.0-stage","stub":true,"maintainers":[{"name":"anchu143","email":"anchuwithdeadline@gmail.com"}],"dist":{"shasum":"88b235665b43d107926413509e44472b6470c1a5","tarball":"https://registry.npmjs.org/u-chan-secrets/-/u-chan-secrets-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-1CKrI3CsNDqI8EK1clVCG8GGl2BaVffS2C9ZuQBRo1sYv8pAZxne1/16kc/XiCfvWtghFPSf2wS1PLJg/3Xa0Q==","signatures":[{"sig":"MEUCIAaOg7dE4JXbQN5EGQym6qNrgbF9UMg2dk2kUy2b24aKAiEAtIx/IX46hEAVAt0Dk9fGHmI8eVxwkK82GWqw2xp5d6Y=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":336},"_npmUser":{"name":"anchu143","email":"anchuwithdeadline@gmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"3.0.0":{"name":"u-chan-secrets","version":"3.0.0","license":"MIT","_id":"u-chan-secrets@3.0.0","maintainers":[{"name":"anchu143","email":"anchuwithdeadline@gmail.com"}],"bin":{"u-chan":"dist/cli.js","u-chan-secrets":"dist/index.js"},"dist":{"shasum":"5146b1661d6ed0ff7b04707ee8b73398b880e723","tarball":"https://registry.npmjs.org/u-chan-secrets/-/u-chan-secrets-3.0.0.tgz","fileCount":64,"integrity":"sha512-AsVrHVL/s8G+SPh9hYDZhQP9yEpR1V865z35Yl8dg9jFxQcXqKlgDUb1UkatRBGs/8hnhLLDigd5kBiFCuH+bg==","signatures":[{"sig":"MEQCIG4NIIfDFZiKgZAh6nm5whokGHRAAPBdgT54uLAHFOpwAiB2x8BUro5fkO2s9lGt2jeHsPnqQKncVnxejy/Nennt/g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIBiHFmXv/eptjxoeyn3bEjKiga2oGkUg+0iXoApQBmLGAiBsQyOjFpbbCDgDHvKB/COeXMhsaM9vZ2Hw9T8L+nuqUA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":228031},"type":"module","_from":"file:C:/Users/ADMIN/AppData/Local/Temp/u-chan-secrets-v3-release/u-chan-secrets-3.0.0.tgz","engines":{"node":">=24"},"scripts":{"test":"vitest run","build":"node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"anchu143","email":"anchuwithdeadline@gmail.com"},"_resolved":"C:\\Users\\ADMIN\\AppData\\Local\\Temp\\u-chan-secrets-v3-release\\u-chan-secrets-3.0.0.tgz","_integrity":"sha512-AsVrHVL/s8G+SPh9hYDZhQP9yEpR1V865z35Yl8dg9jFxQcXqKlgDUb1UkatRBGs/8hnhLLDigd5kBiFCuH+bg==","_npmVersion":"11.17.0","description":"U-Chan Secrets: local MCP server for Bitwarden-backed logins","directories":{},"_nodeVersion":"24.19.0","dependencies":{"zod":"^4.6.7","playwright":"^1.64.1","@modelcontextprotocol/sdk":"^1.32.2"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^5.0.5","typescript":"^7.0.2","@types/node":"^26.6.5"},"_npmOperationalInternal":{"tmp":"tmp/u-chan-secrets_3.0.0_1793215871749_0.023581060111063423","host":"s3://npm-registry-packages-npm-production"}},"3.0.2":{"name":"u-chan-secrets","version":"3.0.2","license":"MIT","_id":"u-chan-secrets@3.0.2","maintainers":[{"name":"anchu143","email":"anchuwithdeadline@gmail.com"}],"bin":{"u-chan":"dist/cli.js","u-chan-secrets":"dist/index.js"},"dist":{"shasum":"a8ad60ec47ad4e8ccc14eaf2497ee9b3b7cbcd38","tarball":"https://registry.npmjs.org/u-chan-secrets/-/u-chan-secrets-3.0.2.tgz","fileCount":65,"integrity":"sha512-dDMAg32uL4UgfS/gC7WJrNE4SwfeOyilz5/jMh/k41HERk0A1yccSuEO1YDowJTjK82WJXGsY4Ial0KiePAzdg==","signatures":[{"sig":"MEUCIAMhhsYr4lJZl0Ua+v4Av7t4EBBiWy62wFk5tL8qLittAiEAi2xWpk4330qeg3BD+PeMPT931YbXMBsQ9uZ2mAqfgd4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIDelHD26SJoueIIaAAFScrKleSh9dN54C/P+vZcO/QOAAiEAmg4XyKkwn8p3z+uFJllbxTUKFjyNKCdqiKX27zxjrAU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":232921},"type":"module","_from":"file:C:/Users/ADMIN/AppData/Local/Temp/u-chan-secrets-v3-release/u-chan-secrets-3.0.2.tgz","engines":{"node":">=24"},"scripts":{"test":"vitest run","build":"node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"anchu143","email":"anchuwithdeadline@gmail.com"},"_resolved":"C:\\Users\\ADMIN\\AppData\\Local\\Temp\\u-chan-secrets-v3-release\\u-chan-secrets-3.0.2.tgz","_integrity":"sha512-dDMAg32uL4UgfS/gC7WJrNE4SwfeOyilz5/jMh/k41HERk0A1yccSuEO1YDowJTjK82WJXGsY4Ial0KiePAzdg==","_npmVersion":"11.17.0","description":"U-Chan Secrets: local MCP server for Bitwarden-backed logins","directories":{},"_nodeVersion":"24.19.0","dependencies":{"zod":"^4.6.7","playwright":"^1.64.1","@modelcontextprotocol/sdk":"^1.32.2"},"_hasShrinkwrap":false,"readmeFilename":"README.md","devDependencies":{"vitest":"^5.0.5","typescript":"^7.0.2","@types/node":"^26.6.5"},"_npmOperationalInternal":{"tmp":"tmp/u-chan-secrets_3.0.2_1793218101287_0.24769782372762783","host":"s3://npm-registry-packages-npm-production"}},"3.0.3":{"name":"u-chan-secrets","version":"3.0.3","license":"MIT","_id":"u-chan-secrets@3.0.3","maintainers":[{"name":"anchu143","email":"anchuwithdeadline@gmail.com"}],"bin":{"u-chan":"dist/cli.js","u-chan-secrets":"dist/index.js"},"dist":{"shasum":"5c2b040e32dfb228c1ccd9e6abb2cac1a5852ce4","tarball":"https://registry.npmjs.org/u-chan-secrets/-/u-chan-secrets-3.0.3.tgz","fileCount":65,"integrity":"sha512-oxIgdbGtxof7m7w2x0Ps+K2xDBLA6rqPnP5pM6pv73v3F43TzSgCAv2bxZdbNHGEwyp+iBKq39FzjwaZkZcfug==","signatures":[{"sig":"MEQCIHIT89kZpRAl6/XN+Q7tX9sefdVAfs2bayHeZnYsaGbxAiAu3gneUpsUp8b6CT+xISO3ZK6v+oOcL63i910Mjrg8Vw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEQCIB7GgVX2epv/0bB9VECxlIcMhfM9ulZf7FGSa/rS1lsYAiBO3OsGKaGNWH3a9MVEws1XNiEoaAkEkDF/YjvCG3I00Q==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":234019},"type":"module","_from":"file:C:/Users/ADMIN/AppData/Local/Temp/u-chan-secrets-v3-release/u-chan-secrets-3.0.3.tgz","engines":{"node":">=24"},"scripts":{"test":"vitest run","build":"node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json","prepublishOnly":"npm run build"},"_npmUser":{"name":"anchu143","email":"anchuwithdeadline@gmail.com"},"_resolved":"C:\\Users\\ADMIN\\AppData\\Local\\Temp\\u-chan-secrets-v3-release\\u-chan-secrets-3.0.3.tgz","_integrity":"sha512-oxIgdbGtxof7m7w2x0Ps+K2xDBLA6rqPnP5pM6pv73v3F43TzSgCAv2bxZdbNHGEwyp+iBKq39FzjwaZkZcfug==","_npmVersion":"11.17.0","description":"U-Chan Secrets: local MCP server for Bitwarden-backed logins","directories":{},"_nodeVersion":"24.19.0","dependencies":{"zod":"^4.6.7","playwright":"^1.64.1","@modelcontextprotocol/sdk":"^1.32.2"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^5.0.5","typescript":"^7.0.2","@types/node":"^26.6.5"},"_npmOperationalInternal":{"tmp":"tmp/u-chan-secrets_3.0.3_1793255283088_0.27157571185570384","host":"s3://npm-registry-packages-npm-production"}},"4.0.0":{"_id":"u-chan-secrets@4.0.0","bin":{"u-chan":"dist/cli.js","u-chan-secrets":"dist/index.js"},"dist":{"shasum":"0f5f91ddb5eab0ab1b0c86a9fc9ab2857fdb8447","tarball":"https://registry.npmjs.org/u-chan-secrets/-/u-chan-secrets-4.0.0.tgz","fileCount":77,"integrity":"sha512-H1+ar4YSvh7SajVJI+t2pWMsoc+6AuefzLHJMPZJ+7K0yjpBJXMvqjftFPrvKsqnbPIDYwARy+27gq8cX1BkSQ==","signatures":[{"sig":"MEYCIQCfBL9fJV6JIId6kck6XTdzyk8fqFXzstpYgLNJ9Y2erQIhAJ7/fv5ElnYNBus/bn5Slzt5bO6uJOhlrw8kH0ydEGk+","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDLx4Rb+uQH4sVMQYNzTGADOnvSQ3DDaMEpWjuwensdGAiEAga+gLazb2CKrr0vT4yMbGlKp27TAzC3msMP29N41Ur4="}],"unpackedSize":306152},"name":"u-chan-secrets","type":"module","_from":"file:C:/Users/ADMIN/AppData/Local/Temp/u-chan-secrets-v4-release/u-chan-secrets-4.0.0.tgz","engines":{"node":">=24"},"license":"MIT","scripts":{"test":"vitest run","build":"node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json","prepublishOnly":"npm run build"},"version":"4.0.0","_npmUser":{"name":"anchu143","email":"anchuwithdeadline@gmail.com"},"_resolved":"C:\\Users\\ADMIN\\AppData\\Local\\Temp\\u-chan-secrets-v4-release\\u-chan-secrets-4.0.0.tgz","_integrity":"sha512-H1+ar4YSvh7SajVJI+t2pWMsoc+6AuefzLHJMPZJ+7K0yjpBJXMvqjftFPrvKsqnbPIDYwARy+27gq8cX1BkSQ==","_npmVersion":"11.17.0","description":"U-Chan Secrets: local MCP server for Bitwarden-backed logins","directories":{},"maintainers":[{"name":"anchu143","email":"anchuwithdeadline@gmail.com"}],"_nodeVersion":"24.19.0","dependencies":{"zod":"^4.6.7","playwright":"^1.64.1","@modelcontextprotocol/sdk":"^1.32.2"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^5.0.5","typescript":"^7.0.2","@types/node":"^26.6.5"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/u-chan-secrets_4.0.0_1793261541742_0.7255017590100202"}}},"time":{"created":"2026-10-28T19:30:14.418Z","modified":"2026-10-29T08:12:22.025Z","0.0.0-stage":"2026-10-28T19:30:14.418Z","3.0.0":"2026-10-28T19:31:11.845Z","3.0.2":"2026-10-28T20:08:21.376Z","3.0.3":"2026-10-29T06:28:03.190Z","4.0.0":"2026-10-29T08:12:21.837Z"},"license":"MIT","description":"U-Chan Secrets: local MCP server for Bitwarden-backed logins","maintainers":[{"name":"anchu143","email":"anchuwithdeadline@gmail.com"}],"readme":"# U-Chan Secrets V4\r\n\r\nA local MCP server that signs into approved websites with Bitwarden credentials. A privileged service performs credential entry in an isolated browser and transfers filtered session state into a dedicated user Chrome profile.\r\n\r\nVersion `4.0.0` adds guided Windows/Codex setup, installed-version and browser-target checks, clearer native status, and CLI proposals for scoped login approval. Protocol and protected-state schema remain version 3.\r\n\r\n**Verification:** Windows/macOS build and test CI is separate from installed-service security verification. Native process identity, input isolation, permissions, and installation rehearsals remain [release gates](docs/attack-checklist.md). See [validation evidence](docs/superpowers/research/2026-10-29-v3-validation.md) and [SECURITY.md](SECURITY.md).\r\n\r\nThe [Windows V4 rollout](docs/superpowers/research/2026-10-29-v4-rollout.md) records matching service/CLI versions, preserved protected state, real setup and fresh MCP/browser checks. It builds on the tightened V3.0.3 [native closeout](docs/superpowers/research/2026-10-29-v3-windows-closeout.md). macOS runtime remains unverified; source merge, installed verification, and package publication are recorded separately.\r\n\r\n## What V3 changes\r\n\r\n- **Diagnose:** `u-chan doctor` explains service, vault, permission, Chrome, and browser-sharing problems without fetching credentials or repairing configuration.\r\n- **Limit approval:** approve one login attempt, a fixed duration, or permanent future logins.\r\n- **Confirm outcomes:** an approved URL or selector provides authentication evidence; generic form completion remains explicitly unconfirmed.\r\n- **Manage access:** `u-chan manage` shows grant pages and recent sanitized activity, with lock, unlock, and revoke actions.\r\n- **Preserve state:** privileged migration backup, schema/downgrade guards, and state-preserving reinstall replace manual editing of protected files.\r\n\r\nWindows Hello and Touch ID remain [research only](docs/superpowers/research/2026-10-29-native-approval.md). Linux, general SSO/OAuth, passkeys, and automated CAPTCHA solving are outside V3.\r\n\r\n## What V4 adds\r\n\r\nUse a normal, non-administrator terminal after installing the matching trusted service:\r\n\r\n```powershell\r\nu-chan setup --json\r\nu-chan setup --client codex --apply\r\nu-chan setup --client codex --apply --replace-existing --start-browser\r\n```\r\n\r\nThe first command only inspects. `--apply` adds missing Codex MCP registrations through the official Codex CLI. `--replace-existing` also permits replacement of recognized simple registrations. Existing configuration is backed up under the Codex configuration directory's `#0 backup` before mutation. Compatible enabled registrations retain custom environment, working directory, tool filters, timeouts, and other settings. Incompatible custom registrations, conflicting target overrides, disabled entries, and HTTP transports require manual configuration and remain untouched. Partial failures retain completed changes and the backup; setup never restores an obsolete whole configuration over concurrent edits.\r\n\r\n`--start-browser` explicitly starts the dedicated Chrome profile in the background when its endpoint is unhealthy. No startup task is added. Setup refuses elevated execution and known service/desktop browser-target mismatches. It never installs the privileged service or changes UAC. Run `u-chan install` separately from a trusted administrator terminal.\r\n\r\nSetup reports `configured` or `needs_attention`, plus `sharing` and `restartRequired`. `process_configured` means matching process arguments were observed; it does not verify active AI-session ownership. Unobservable sharing remains `unobserved`. Restart the AI session after registration changes. Exit codes: 1 means attention required, 2 means configured with restart required, and 0 means configured without a known restart requirement. A locked vault remains a valid installed state.\r\n\r\nAutomatic registration supports Codex on Windows only. Configure other clients manually using their documented MCP commands. macOS runtime remains unverified. `doctor` compares the actual CLI and installed service versions, both browser targets, and Windows UAC policy; missing metadata remains unknown. `manage` shows the installed service version and browser status.\r\n\r\nPropose a site grant with an explicit success condition:\r\n\r\n```sh\r\nu-chan allow example.com --login-url https://example.com/login --item \"Example account\" --once --success-url https://example.com/dashboard\r\nu-chan allow example.com --login-url https://example.com/login --item \"Example account\" --minutes 30 --success-selector \"button[data-action='sign-out']\"\r\n```\r\n\r\nThe service still requires protected approval. The CLI defaults to one login attempt; timed approvals accept 1–1440 whole minutes, and `--permanent` requests permanent future logins. URL and selector success conditions are mutually exclusive. Without one, login may return `authentication_unconfirmed`; independently verify the signed-in page. Grant expiry does not log out an already transferred browser session.\r\n\r\n## Architecture\r\n\r\n```mermaid\r\nflowchart TD\r\n    AI[\"Claude Code / other MCP client\"] --> MCP[\"Thin MCP client: user account\"]\r\n    MCP --> IPC[\"Local IPC with caller identity checks\"]\r\n    IPC --> SERVICE[\"Privileged service: SYSTEM / root\"]\r\n    SERVICE --> VAULT[\"Bitwarden CLI and private vault data\"]\r\n    SERVICE --> PROMPT[\"Service-owned native prompts\"]\r\n    SERVICE --> BROWSER[\"Isolated service-owned Chromium\"]\r\n    BROWSER -->|\"Filtered cookies and localStorage\"| CHROME[\"Dedicated user Chrome\"]\r\n    AI --> PW[\"Playwright MCP\"]\r\n    PW -->|\"Shared CDP endpoint\"| CHROME\r\n```\r\n\r\nThe service owns the allowlist, settings, audit log, runtime, dependencies, Bitwarden executable, and isolated Chromium bundle. The thin client holds no vault credentials. Windows prompts require SYSTEM identity and a separate input desktop; replies cross sessions through a SYSTEM-only named pipe. macOS uses secure password entry and permits hardcore mode only.\r\n\r\nA Bitwarden session is held in service memory and passed to privileged Bitwarden subprocesses when needed. It is not stored in desktop configuration or a session file. Vault access expires after the configured idle interval (12 hours by default), manual lock, restart, or reboot. This does not claim cryptographic zeroization of JavaScript strings or OS memory.\r\n\r\n**After session transfer, the AI can use the signed-in website.** Grant expiry and revocation stop future U-Chan logins; they do not invalidate existing Chrome sessions or prevent actions inside those sessions. Revocation waits for an earlier queued login to finish.\r\n\r\n## Prerequisites\r\n\r\n- Windows or macOS.\r\n- Node.js 24+.\r\n- A native Bitwarden CLI executable: `bw.exe` on Windows or `bw` on macOS. The Windows npm `.cmd` shim is unsupported.\r\n- Google Chrome for the user-side dedicated profile.\r\n- The matching Playwright Chromium installation for service staging.\r\n\r\nInstall from a trusted shell before granting an AI unrestricted user-account access. On Windows, use UAC **Always notify** or run the AI from a standard user account. Existing administrator/root compromise is outside the threat model.\r\n\r\n## Build and install from source\r\n\r\nUse a reviewed checkout for the desired source version. Unversioned npm installation can select a different published version; the package metadata in this repository is not proof of npm publication.\r\n\r\n```sh\r\ngit clone https://github.com/anchuwithdeadline/u-chan-secrets.git\r\ncd u-chan-secrets\r\nnpm ci\r\nnpm run build\r\nnpx playwright install chromium\r\n```\r\n\r\nThe following setup commands use `node dist/cli.js` from that checkout. After a matching package is globally installed, `u-chan` invokes the same CLI. The globally installed MCP command is `u-chan-secrets`.\r\n\r\n### Windows\r\n\r\nFrom a trusted elevated PowerShell terminal in the checkout:\r\n\r\n```powershell\r\nnode dist/cli.js install --mode hardcore\r\n```\r\n\r\nWindows also supports `--mode easy`; omitting the mode uses the Windows installer default, easy. The installer generates a phrase unless one is supplied. Reinstall preserves existing owner/settings and grants rather than applying new mode/phrase arguments over them.\r\n\r\nFor the one-time login to the service's private Bitwarden store, use the copied native executable in that same elevated terminal:\r\n\r\n```powershell\r\n$env:BITWARDENCLI_APPDATA_DIR = Join-Path $env:ProgramData 'u-chan-secrets\\bw-data'\r\nRemove-Item Env:\\BW_SESSION -ErrorAction SilentlyContinue\r\n& (Join-Path $env:ProgramData 'u-chan-secrets\\bin\\bw.exe') login\r\nRemove-Item Env:\\BITWARDENCLI_APPDATA_DIR\r\n```\r\n\r\n**Do not use `scripts/debug-install.bat` as a V3 setup or upgrade path.** That legacy script invokes uninstall, which deletes service data, and exports protected settings into the checkout. Use the CLI installer above.\r\n\r\n### macOS\r\n\r\nFrom the trusted checkout:\r\n\r\n```bash\r\nsudo \"$(command -v node)\" dist/cli.js install\r\nsudo env -u BW_SESSION \\\r\n  BITWARDENCLI_APPDATA_DIR=\"/Library/Application Support/u-chan-secrets/bw-data\" \\\r\n  \"/Library/Application Support/u-chan-secrets/bin/bw\" login\r\n```\r\n\r\nThe daemon uses `/Library/Application Support/u-chan-secrets` and `/Library/LaunchDaemons/com.uchan.secrets.plist`. macOS always uses hardcore approval; easy mode is refused.\r\n\r\n### Register MCP and shared Chrome\r\n\r\nFor a source checkout, register the absolute path to the thin client:\r\n\r\n```sh\r\nclaude mcp add u-chan-secrets -- node \"/absolute/path/to/u-chan-secrets/dist/index.js\"\r\nclaude mcp add playwright -- npx @playwright/mcp@latest --cdp-endpoint http://127.0.0.1:9222\r\n```\r\n\r\nIf a Playwright MCP registration already exists, replace it with the shared-CDP configuration and restart the AI session. A globally installed matching package can instead register `claude mcp add u-chan-secrets -- u-chan-secrets`.\r\n\r\nStart the dedicated Chrome profile from the checkout:\r\n\r\n| Platform | Command |\r\n|---|---|\r\n| Windows | `powershell -File scripts\\start-chrome.ps1` |\r\n| macOS | `bash scripts/start-chrome.sh` |\r\n\r\nUse a normal user terminal for daily operations:\r\n\r\n```sh\r\nnode dist/cli.js doctor\r\nnode dist/cli.js unlock\r\n```\r\n\r\nCheck the phrase in the genuine protected prompt before entering a password. Never send passwords, TOTP seeds/codes, or vault session keys to an AI conversation.\r\n\r\n## Daily commands\r\n\r\nThe table uses the globally installed `u-chan` spelling; from source use `node dist/cli.js` with the same arguments.\r\n\r\nIn Windows PowerShell, use `u-chan.cmd` if execution policy blocks npm's `.ps1` shim, for example `u-chan.cmd doctor --json`. No machine execution-policy change is needed.\r\n\r\n| Command | Purpose |\r\n|---|---|\r\n| `doctor [--json]` | Read-only diagnostic report and safe next actions |\r\n| `setup [--client codex] [--apply] [--replace-existing] [--start-browser] [--json]` | Windows desktop inspection and explicit Codex/browser setup |\r\n| `allow <domain> --login-url <https-url> --item <label> [--once\\|--minutes N\\|--permanent] [--success-url URL\\|--success-selector SELECTOR]` | Propose a scoped grant through protected approval |\r\n| `manage` | Native status, grant pages, recent activity, lock/unlock, and revocation |\r\n| `unlock` | Request the protected master-password prompt |\r\n| `lock` | Forget the service's vault session and request vault lock |\r\n| `mode <easy\\|hardcore>` | Change approval mode; lowering protection requires a protected password check |\r\n| `audit [limit]` | Read recent service audit records |\r\n| `import-v1 [path]` | Approve each imported entry in a protected window; imported grants are permanent |\r\n| `update` | Request a verified compatible package update; some changes require administrator reinstall |\r\n| `install [--mode <easy\\|hardcore>] [--phrase <phrase>]` | Privileged install/reinstall; existing settings are preserved |\r\n| `uninstall` | Privileged removal of the service **and all its data** |\r\n\r\nDoctor reports `pass`, `fail`, or `unknown`. Exit 0 means required checks passed; 1 means a required check failed; 2 means required checks remain unknown without a failure. A locked vault is a valid state with an unlock instruction. Unobservable Playwright sharing is advisory; a known mismatch fails doctor. Diagnosis never retrieves credentials, opens an unlock prompt, or changes configuration.\r\n\r\nManage shows 20 grants per page. It cannot create or extend a grant. Unlock closes the management dialog before opening the protected password prompt.\r\n\r\n## MCP tools and approvals\r\n\r\nThe five AI-facing tools remain:\r\n\r\n| Tool | Behavior |\r\n|---|---|\r\n| `status` | Vault state, approval mode, and observable Playwright sharing |\r\n| `request_allow(domain, login_url, item, selectors?, grant?, success?)` | Request protected approval of the complete entry and duration |\r\n| `login(domain)` | Check/reserve the grant, sign in privately, and transfer permitted session state |\r\n| `list_allowed` | Show authorized item/hosts and permanent, timed, expired, or exhausted grant state |\r\n| `revoke(domain)` | Remove a grant without another approval; waits behind an earlier login |\r\n\r\nUse the Bitwarden item ID or name supplied by the user; do not guess a vault item. Optional selectors cover username, password, submit, and OTP fields.\r\n\r\nExample `request_allow` arguments:\r\n\r\n```json\r\n{\r\n  \"domain\": \"example.com\",\r\n  \"login_url\": \"https://example.com/login\",\r\n  \"item\": \"the Bitwarden item ID supplied by the user\",\r\n  \"grant\": { \"kind\": \"timed\", \"minutes\": 30 },\r\n  \"success\": { \"url\": \"https://example.com/dashboard\" }\r\n}\r\n```\r\n\r\n| Grant | Meaning |\r\n|---|---|\r\n| `{ \"kind\": \"once\" }` | One attempt after vault/Chrome preflight; failure after reservation still consumes it |\r\n| `{ \"kind\": \"timed\", \"minutes\": 30 }` | Future logins until the exact approved UTC expiry; integer range 1–1,440 minutes |\r\n| `{ \"kind\": \"permanent\" }` | Permanent future logins |\r\n| Omitted | Permanent, preserving existing callers; the protected prompt states this |\r\n\r\nThe AI proposes policy; the human authorizes it through the protected prompt. V3 clients refuse new options against a service that lacks the corresponding capability.\r\n\r\nChanging identity, hosts, selectors, duration, or success conditions requires a new approval. A timed request that expires while its window is open is refused. Detected backward-clock changes invalidate affected persisted timed grants; renewed approval is required. Clock changes while the service is stopped cannot be reconstructed.\r\n\r\nEasy mode exists only on Windows. Hardcore approvals require the master password. Protected prompts time out after two minutes. Five incorrect password attempts lock password-checked operations for 15 minutes.\r\n\r\n### Login results and 2FA\r\n\r\nA success condition is one exact approved HTTPS URL or a visible-element selector, such as `{ \"selector\": \"#signed-in-account\" }`. Choose evidence specific to the authenticated page: `body` or another generic element is not meaningful proof. The service checks the allowed host around evidence evaluation and transfer.\r\n\r\nWithout approved evidence, a generic completed flow may transfer filtered state but returns `ok: false` with `authentication_unconfirmed`. Inspect Chrome before continuing. An unmet configured condition prevents transfer. Other fixed result codes distinguish grant expiry/exhaustion, vault/Chrome availability, human verification, timeout, and transfer failure.\r\n\r\nThe service supports Bitwarden TOTP for recognized one-time-code fields. Passwords, TOTP seeds, and generated codes stay inside the privileged login flow. CAPTCHA, device verification, and unsupported challenges require the user; the AI must not request the underlying credentials.\r\n\r\n## Upgrade, backup, and rollback\r\n\r\nUse a trusted administrator reinstall for the first V3 installation; the thin client alone does not upgrade native helpers or private executables. Windows reinstall stops the service, waits for shutdown, stages a fresh private program copy, preserves the old program under protected `#0 backup`, and reuses service registration. Existing settings and grants remain.\r\n\r\nBefore the first grant-state mutation, the service creates a protected `#0 backup/v2-before-v3` snapshot and a `schema.json` marker. The snapshot may contain privileged configuration and encrypted vault data: never copy it into a user-readable checkout. Incomplete backups block mutation rather than being overwritten.\r\n\r\nSupported V3 tooling refuses V2 downgrade after migration. Historical V2 administrator tools cannot enforce a newer schema guard. A deliberate rollback requires stopping the service, inspecting/restoring the protected pre-V3 state, and acknowledging that old permanent approvals return. Do not uninstall as an upgrade shortcut: uninstall deletes the data.\r\n\r\nPackage updates verify registry signatures and integrity and retain private dependencies. Changed dependencies or native helpers require a trusted administrator reinstall. Expired/exhausted grants and already transferred website sessions are separate from vault lock and upgrade state.\r\n\r\nVersions 3.0.0–3.0.2 have an npm signature-verification defect and cannot reliably bootstrap their own update. Install the matching corrected package from a trusted shell, then use the administrator reinstall above. Version 3.0.3 requires SHA-512 integrity and a valid signature from its pinned npm key; unsigned repository-attestation JSON cannot replace that signature. Future signing-key rotation fails closed and requires a trusted verifier upgrade.\r\n\r\nFor V1 data, use `u-chan import-v1 [path]`: each entry requires protected approval. Retire user-side Bitwarden sessions and the old `bw-session` file through a trusted migration process; never copy them into the service as trusted authorization.\r\n\r\n## Validation and security\r\n\r\n```sh\r\nnpm test\r\nnpm run build\r\n```\r\n\r\n[CI](https://github.com/anchuwithdeadline/u-chan-secrets/actions/workflows/ci.yml) runs builds/tests on Windows and macOS. CodeQL checks source separately. Passing these checks does not prove actual SYSTEM/root prompt isolation or certify an installed service.\r\n\r\nBefore release or reliance on the security boundary, perform the [manual attack checklist](docs/attack-checklist.md). See [validation and remaining native checks](docs/superpowers/research/2026-10-29-v3-validation.md), [security policy](SECURITY.md), and [V3 change notes](CHANGELOG.md).\r\n\r\n## License\r\n\r\n[MIT](LICENSE)\r\n","readmeFilename":"README.md"}