u-chan-secrets 0.0.0-stage → 3.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chu Đức An
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,218 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# U-Chan Secrets V3
+
+A 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.
+
+V3 adds diagnostics, temporary approvals, explicit login outcomes, and a native management window. The source version is `3.0.2`; merging this repository does not publish an npm package or update an installed service.
+
+**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).
+
+## What V3 changes
+
+- **Diagnose:** `u-chan doctor` explains service, vault, permission, Chrome, and browser-sharing problems without fetching credentials or repairing configuration.
+- **Limit approval:** approve one login attempt, a fixed duration, or permanent future logins.
+- **Confirm outcomes:** an approved URL or selector provides authentication evidence; generic form completion remains explicitly unconfirmed.
+- **Manage access:** `u-chan manage` shows grant pages and recent sanitized activity, with lock, unlock, and revoke actions.
+- **Preserve state:** privileged migration backup, schema/downgrade guards, and state-preserving reinstall replace manual editing of protected files.
+
+Windows 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.
+
+## Architecture
+
+```mermaid
+flowchart TD
+    AI["Claude Code / other MCP client"] --> MCP["Thin MCP client: user account"]
+    MCP --> IPC["Local IPC with caller identity checks"]
+    IPC --> SERVICE["Privileged service: SYSTEM / root"]
+    SERVICE --> VAULT["Bitwarden CLI and private vault data"]
+    SERVICE --> PROMPT["Service-owned native prompts"]
+    SERVICE --> BROWSER["Isolated service-owned Chromium"]
+    BROWSER -->|"Filtered cookies and localStorage"| CHROME["Dedicated user Chrome"]
+    AI --> PW["Playwright MCP"]
+    PW -->|"Shared CDP endpoint"| CHROME
+```
+
+The 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.
+
+A 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.
+
+**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.
+
+## Prerequisites
+
+- Windows or macOS.
+- Node.js 24+.
+- A native Bitwarden CLI executable: `bw.exe` on Windows or `bw` on macOS. The Windows npm `.cmd` shim is unsupported.
+- Google Chrome for the user-side dedicated profile.
+- The matching Playwright Chromium installation for service staging.
+
+Install 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.
+
+## Build and install from source
+
+Use the checkout for the V3 source version. Unversioned npm installation can select a different published version; the package metadata in this repository is not proof of npm publication.
+
+```sh
+git clone https://github.com/anchuwithdeadline/u-chan-secrets.git
+cd u-chan-secrets
+npm ci
+npm run build
+npx playwright install chromium
+```
+
+The 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`.
+
+### Windows
+
+From a trusted elevated PowerShell terminal in the checkout:
+
+```powershell
+node dist/cli.js install --mode hardcore
+```
+
+Windows 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.
+
+For the one-time login to the service's private Bitwarden store, use the copied native executable in that same elevated terminal:
+
+```powershell
+$env:BITWARDENCLI_APPDATA_DIR = Join-Path $env:ProgramData 'u-chan-secrets\bw-data'
+Remove-Item Env:\BW_SESSION -ErrorAction SilentlyContinue
+& (Join-Path $env:ProgramData 'u-chan-secrets\bin\bw.exe') login
+Remove-Item Env:\BITWARDENCLI_APPDATA_DIR
+```
+
+**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.
+
+### macOS
+
+From the trusted checkout:
+
+```bash
+sudo "$(command -v node)" dist/cli.js install
+sudo env -u BW_SESSION \
+  BITWARDENCLI_APPDATA_DIR="/Library/Application Support/u-chan-secrets/bw-data" \
+  "/Library/Application Support/u-chan-secrets/bin/bw" login
+```
+
+The daemon uses `/Library/Application Support/u-chan-secrets` and `/Library/LaunchDaemons/com.uchan.secrets.plist`. macOS always uses hardcore approval; easy mode is refused.
+
+### Register MCP and shared Chrome
+
+For a source checkout, register the absolute path to the thin client:
+
+```sh
+claude mcp add u-chan-secrets -- node "/absolute/path/to/u-chan-secrets/dist/index.js"
+claude mcp add playwright -- npx @playwright/mcp@latest --cdp-endpoint http://127.0.0.1:9222
+```
+
+If 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`.
+
+Start the dedicated Chrome profile from the checkout:
+
+| Platform | Command |
+|---|---|
+| Windows | `powershell -File scripts\start-chrome.ps1` |
+| macOS | `bash scripts/start-chrome.sh` |
+
+Use a normal user terminal for daily operations:
+
+```sh
+node dist/cli.js doctor
+node dist/cli.js unlock
+```
+
+Check 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.
+
+## Daily commands
+
+The table uses the globally installed `u-chan` spelling; from source use `node dist/cli.js` with the same arguments.
+
+| Command | Purpose |
+|---|---|
+| `doctor [--json]` | Read-only diagnostic report and safe next actions |
+| `manage` | Native status, grant pages, recent activity, lock/unlock, and revocation |
+| `unlock` | Request the protected master-password prompt |
+| `lock` | Forget the service's vault session and request vault lock |
+| `mode <easy\|hardcore>` | Change approval mode; lowering protection requires a protected password check |
+| `audit [limit]` | Read recent service audit records |
+| `import-v1 [path]` | Approve each imported entry in a protected window; imported grants are permanent |
+| `update` | Request a verified compatible package update; some changes require administrator reinstall |
+| `install [--mode <easy\|hardcore>] [--phrase <phrase>]` | Privileged install/reinstall; existing settings are preserved |
+| `uninstall` | Privileged removal of the service **and all its data** |
+
+Doctor 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.
+
+Manage shows 20 grants per page. It cannot create or extend a grant. Unlock closes the management dialog before opening the protected password prompt.
+
+## MCP tools and approvals
+
+The five AI-facing tools remain:
+
+| Tool | Behavior |
+|---|---|
+| `status` | Vault state, approval mode, and observable Playwright sharing |
+| `request_allow(domain, login_url, item, selectors?, grant?, success?)` | Request protected approval of the complete entry and duration |
+| `login(domain)` | Check/reserve the grant, sign in privately, and transfer permitted session state |
+| `list_allowed` | Show authorized item/hosts and permanent, timed, expired, or exhausted grant state |
+| `revoke(domain)` | Remove a grant without another approval; waits behind an earlier login |
+
+Use 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.
+
+Example `request_allow` arguments:
+
+```json
+{
+  "domain": "example.com",
+  "login_url": "https://example.com/login",
+  "item": "the Bitwarden item ID supplied by the user",
+  "grant": { "kind": "timed", "minutes": 30 },
+  "success": { "url": "https://example.com/dashboard" }
+}
+```
+
+| Grant | Meaning |
+|---|---|
+| `{ "kind": "once" }` | One attempt after vault/Chrome preflight; failure after reservation still consumes it |
+| `{ "kind": "timed", "minutes": 30 }` | Future logins until the exact approved UTC expiry; integer range 1–1,440 minutes |
+| `{ "kind": "permanent" }` | Permanent future logins |
+| Omitted | Permanent, preserving existing callers; the protected prompt states this |
+
+The AI proposes policy; the human authorizes it through the protected prompt. V3 clients refuse new options against a service that lacks the corresponding capability.
+
+Changing 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.
+
+Easy 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.
+
+### Login results and 2FA
+
+A 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.
+
+Without 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.
+
+The 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.
+
+## Upgrade, backup, and rollback
+
+Use 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.
+
+Before 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.
+
+Supported 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.
+
+Package 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.
+
+For 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.
+
+## Validation and security
+
+```sh
+npm test
+npm run build
+```
+
+[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.
+
+Before 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).
+
+## License
+
+[MIT](LICENSE)

package/dist/cli.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { posix, win32 } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { IpcClient } from './ipc/client.js';
+import { defaultEndpoint } from './ipc/endpoint.js';
+import { MAX_FRAME, encode } from './ipc/protocol.js';
+import { runDoctor, doctorExitCode, checkPlaywrightNow, chromeState, SERVICE_DIAGNOSTIC_TIMEOUT_MS } from './core/doctor.js';
+import { loadConfig } from './core/config.js';
+const USAGE = 'usage: u-chan install [--mode <easy|hardcore>] [--phrase <phrase>] | uninstall | unlock | lock | mode <easy|hardcore> | import-v1 [path] | audit [limit] | update | doctor [--json] | manage';
+/** import-v1 shows one approval window per entry, each open for up to 2 minutes, one after another. */
+export const IMPORT_PROMPT_MS = 120000;
+export const IMPORT_MARGIN_MS = 60000;
+export const importTimeoutMs = (count) => count * IMPORT_PROMPT_MS + IMPORT_MARGIN_MS;
+/** V1 kept its allowlist in %APPDATA%\u-chan-secrets (the user's profile). */
+function defaultV1Path(env, platform) {
+    const path = platform === 'win32' ? win32 : posix;
+    return path.join(env.APPDATA ?? path.join(homedir(), 'AppData', 'Roaming'), 'u-chan-secrets', 'allowlist.json');
+}
+/** Returns the process exit code: 0 on success, 1 on failure or bad usage. */
+export async function main(argv, d) {
+    const [cmd, arg, ...rest] = argv;
+    let call;
+    const doctor = d.doctor ?? (() => runDoctor({
+        platform: d.platform,
+        registration: async () => d.platform === 'win32' ? (await import('./platform/windows/doctor.js')).checkWindowsRegistration() : d.platform === 'darwin' ? (await import('./platform/darwin/doctor.js')).checkDarwinRegistration() : 'fail',
+        service: async () => {
+            const r = await d.connect({ timeoutMs: SERVICE_DIAGNOSTIC_TIMEOUT_MS }).diagnose();
+            if (!r.ok)
+                throw new Error('unavailable');
+            const s = JSON.parse(r.message);
+            if (!s || typeof s !== 'object')
+                throw new Error('invalid diagnostics');
+            return s;
+        },
+        chrome: () => chromeState(loadConfig(d.env, d.platform).cdpEndpoint),
+        playwright: async () => {
+            if (d.platform !== 'win32')
+                return 'unknown';
+            const state = await checkPlaywrightNow();
+            return state === 'ok' ? 'pass' : state === 'missing' ? 'fail' : 'unknown';
+        },
+    }));
+    const printDoctor = (r) => d.out(r.checks.map(c => `${c.state.toUpperCase()} ${c.id}: ${c.message}${c.nextAction ? ' ' + c.nextAction : ''}`).join('\n'));
+    if (cmd === 'doctor' && (arg === undefined || arg === '--json') && rest.length === 0) {
+        const r = await doctor();
+        if (arg === '--json')
+            d.out(JSON.stringify(r));
+        else
+            printDoctor(r);
+        return doctorExitCode(r);
+    }
+    if (cmd === 'install') {
+        let mode;
+        let phrase;
+        let valid = true;
+        const args = arg !== undefined ? [arg, ...rest] : [];
+        for (let i = 0; i < args.length; i++) {
+            if (args[i] === '--mode' && (args[i + 1] === 'easy' || args[i + 1] === 'hardcore')) {
+                mode = args[++i];
+            }
+            else if (args[i] === '--phrase' && args[i + 1] !== undefined) {
+                phrase = args[++i];
+            }
+            else {
+                valid = false;
+                break;
+            }
+        }
+        if (!valid) {
+            d.err(USAGE);
+            return 1;
+        }
+        call = async () => {
+            if (d.install)
+                return d.install({ mode, phrase });
+            if (d.platform === 'win32') {
+                const { installWindowsService } = await import('./platform/windows/install.js');
+                return installWindowsService({ mode, phrase, out: d.out, err: d.err });
+            }
+            if (d.platform === 'darwin') {
+                const { macosInstall } = await import('./platform/darwin/lifecycle.js');
+                return macosInstall({ mode, phrase, out: d.out, err: d.err });
+            }
+            return { ok: false, message: `install is not supported on ${d.platform} yet` };
+        };
+    }
+    else if (cmd === 'uninstall' && arg === undefined) {
+        call = async () => {
+            if (d.uninstall)
+                return d.uninstall();
+            if (d.platform === 'win32') {
+                const { uninstallWindowsService } = await import('./platform/windows/install.js');
+                return uninstallWindowsService({ out: d.out, err: d.err });
+            }
+            if (d.platform === 'darwin') {
+                const { macosUninstall } = await import('./platform/darwin/lifecycle.js');
+                return macosUninstall({ out: d.out, err: d.err });
+            }
+            return { ok: false, message: `uninstall is not supported on ${d.platform} yet` };
+        };
+    }
+    else if (cmd === 'unlock' && arg === undefined) {
+        call = () => d.connect({}).unlock();
+    }
+    else if (cmd === 'lock' && arg === undefined) {
+        call = () => d.connect({}).lock();
+    }
+    else if (cmd === 'mode' && (arg === 'easy' || arg === 'hardcore') && rest.length === 0) {
+        call = () => d.connect({}).setMode(arg);
+    }
+    else if (cmd === 'import-v1' && rest.length === 0) {
+        const path = arg ?? defaultV1Path(d.env, d.platform);
+        let text;
+        try {
+            text = await d.readFile(path);
+        }
+        catch (e) {
+            const code = e?.code;
+            d.err(code === 'ENOENT' ? `no V1 allowlist found at ${path}` : `could not read ${path} (${code ?? 'error'})`);
+            return 1;
+        }
+        let entries;
+        try {
+            entries = JSON.parse(text.charCodeAt(0) === 0xfeff ? text.slice(1) : text);
+        }
+        catch {
+            d.err(`${path} is not valid JSON`);
+            return 1;
+        }
+        if (!Array.isArray(entries)) {
+            d.err(`${path} is not a V1 allowlist (expected a JSON array)`);
+            return 1;
+        }
+        // The service drops frames over MAX_FRAME; a worst-case id keeps this estimate above the real frame.
+        const frame = encode({ id: Number.MAX_SAFE_INTEGER, method: 'import_v1', params: { entries } });
+        if (Buffer.byteLength(frame, 'utf8') > MAX_FRAME) {
+            d.err('V1 allowlist is too large to import in one go');
+            return 1;
+        }
+        const list = entries;
+        call = () => d.connect({ timeoutMs: importTimeoutMs(list.length) }).importV1(list);
+    }
+    else if (cmd === 'audit' && rest.length === 0) {
+        let limit;
+        if (arg !== undefined) {
+            const parsed = Number(arg);
+            if (!Number.isInteger(parsed) || parsed <= 0) {
+                d.err('limit must be a positive integer');
+                return 1;
+            }
+            limit = parsed;
+        }
+        call = () => d.connect({}).audit(limit);
+    }
+    else if (cmd === 'update' && arg === undefined) {
+        call = () => d.connect({ timeoutMs: 120000 }).update();
+    }
+    else if (cmd === 'manage' && arg === undefined) {
+        call = () => d.connect({ timeoutMs: 15 * 60_000 }).manage();
+    }
+    if (!call) {
+        d.err(USAGE);
+        return 1;
+    }
+    const r = await call();
+    if (r.ok)
+        d.out(r.message);
+    else
+        d.err(r.message);
+    if (r.ok && cmd === 'install' && !d.install)
+        printDoctor(await doctor());
+    return r.ok ? 0 : 1;
+}
+const isEntry = (() => {
+    try {
+        return !!process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+})();
+if (isEntry) {
+    const code = await main(process.argv.slice(2), {
+        connect: (opts) => new IpcClient(defaultEndpoint(process.env, process.platform), opts),
+        env: process.env,
+        platform: process.platform,
+        readFile: (p) => readFile(p, 'utf8'),
+        out: (l) => console.log(l),
+        err: (l) => console.error(l),
+    });
+    process.exitCode = code;
+}

package/dist/core/abort.js

@@ -0,0 +1,30 @@
+/** Cancels owned resources before rejecting; late initialization results are disposed. */
+export async function abortable(work, signal, cancel = async () => { }, disposeLate) {
+    if (!signal)
+        return work;
+    let cleanup;
+    let reject;
+    const stopped = new Promise((_resolve, r) => { reject = r; });
+    const abort = () => {
+        cleanup ??= Promise.resolve().then(cancel);
+        void cleanup.then(() => reject(signal.reason), reject);
+    };
+    const running = work.then(async (value) => {
+        if (signal.aborted) {
+            await disposeLate?.(value);
+            throw signal.reason;
+        }
+        return value;
+    });
+    signal.addEventListener('abort', abort, { once: true });
+    if (signal.aborted)
+        abort();
+    try {
+        return await Promise.race([running, stopped]);
+    }
+    finally {
+        signal.removeEventListener('abort', abort);
+        if (signal.aborted)
+            await cleanup?.catch(() => { });
+    }
+}

package/dist/core/allowlist.js

@@ -0,0 +1,139 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { UserFacingError } from './types.js';
+import { validOptions } from './policy.js';
+export class AllowlistStore {
+    path;
+    beforeWrite;
+    constructor(path, beforeWrite) {
+        this.path = path;
+        this.beforeWrite = beforeWrite;
+    }
+    async list() {
+        let raw;
+        try {
+            raw = await readFile(this.path, 'utf8');
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return [];
+            throw e;
+        }
+        let data;
+        try {
+            data = JSON.parse(raw);
+        }
+        catch {
+            throw new UserFacingError('allowlist.json is invalid');
+        }
+        if (!Array.isArray(data))
+            throw new UserFacingError('allowlist.json is invalid');
+        return data.filter(isValidEntry);
+    }
+    async get(domain) {
+        const d = normalizeDomain(domain);
+        if (!d)
+            return undefined;
+        return (await this.list()).find((e) => e.domain === d);
+    }
+    async upsert(entry) {
+        if (!isValidEntry(entry))
+            throw new UserFacingError('invalid grant policy', 'invalid_policy');
+        const d = normalizeDomain(entry.domain);
+        if (!d)
+            throw new UserFacingError('domain is empty or invalid');
+        const rest = (await this.list()).filter((e) => e.domain !== d);
+        await this.write([...rest, { ...entry, domain: d }]);
+    }
+    async remove(domain) {
+        const d = normalizeDomain(domain);
+        if (!d)
+            return false;
+        const all = await this.list();
+        const rest = all.filter((e) => e.domain !== d);
+        if (rest.length === all.length)
+            return false;
+        await this.write(rest);
+        return true;
+    }
+    async write(entries) {
+        await this.beforeWrite?.();
+        await mkdir(dirname(this.path), { recursive: true });
+        const tmp = `${this.path}.${process.pid}.${Date.now()}.tmp`;
+        await writeFile(tmp, JSON.stringify(entries, null, 2));
+        await rename(tmp, this.path);
+    }
+}
+export function isValidEntry(e) {
+    if (typeof e !== 'object' || e === null)
+        return false;
+    const o = e;
+    return (typeof o.domain === 'string' &&
+        typeof o.loginUrl === 'string' &&
+        typeof o.item === 'string' &&
+        Array.isArray(o.hosts) &&
+        o.hosts.every((h) => typeof h === 'string')
+        && (o.expiresAt === undefined || (typeof o.expiresAt === 'string' && Number.isFinite(Date.parse(o.expiresAt)) && new Date(o.expiresAt).toISOString() === o.expiresAt))
+        && (o.remainingUses === undefined || (Number.isSafeInteger(o.remainingUses) && o.remainingUses >= 0))
+        && (o.grantId === undefined || (typeof o.grantId === 'string' && o.grantId.length > 0 && o.grantId.length <= 100))
+        && (o.success === undefined || validOptions({ success: o.success })));
+}
+/** Strips control, format (e.g. bidi overrides), line- and paragraph-separator characters (CR, LF, tab included). */
+export const clean = (s) => String(s ?? '').replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, '');
+const SELECTOR_KEYS = ['username', 'password', 'submit', 'otp'];
+/** Only the four known keys with non-empty string values, cleaned. */
+export function cleanSelectors(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const o = raw;
+    const out = {};
+    for (const k of SELECTOR_KEYS) {
+        const v = o[k];
+        if (typeof v === 'string' && clean(v))
+            out[k] = clean(v);
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+export const selectorsLine = (s) => `Selectors: ${Object.entries(s).map(([k, v]) => `${k}=${v}`).join(', ')}`;
+/** Exact, case-insensitive hostname match over https only. No wildcards. */
+export function isHostAllowed(entry, url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        return false;
+    }
+    if (u.protocol !== 'https:')
+        return false;
+    if (!Array.isArray(entry.hosts) || !entry.hosts.every((h) => typeof h === 'string'))
+        return false;
+    return entry.hosts.includes(u.hostname.toLowerCase());
+}
+export function normalizeDomain(input) {
+    const s = input.trim().toLowerCase().replace(/^[a-z][a-z0-9+.-]*:\/\//, '').split(/[/?#]/)[0];
+    if (!s)
+        return '';
+    try {
+        return new URL(`https://${s}`).hostname;
+    }
+    catch {
+        return '';
+    }
+}
+export function buildEntry(domain, loginUrl, item, existing) {
+    const d = normalizeDomain(domain);
+    if (!d)
+        throw new UserFacingError('domain is empty or invalid');
+    let u;
+    try {
+        u = new URL(loginUrl);
+    }
+    catch {
+        throw new UserFacingError('loginUrl is not a valid URL');
+    }
+    if (u.protocol !== 'https:')
+        throw new UserFacingError('loginUrl must use https');
+    const hosts = [...new Set([...(existing?.hosts ?? []), d, u.hostname.toLowerCase()])];
+    return { ...existing, domain: d, hosts, loginUrl, item };
+}

package/dist/core/audit.js

@@ -0,0 +1,41 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export class FileAuditLog {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    async record(event) {
+        await mkdir(dirname(this.path), { recursive: true });
+        const { action, domain, result } = event;
+        await appendFile(this.path, JSON.stringify({ ts: new Date().toISOString(), action, domain, result }) + '\n');
+    }
+    async readTail(limit = 100) {
+        let content;
+        try {
+            content = await readFile(this.path, 'utf8');
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return [];
+            throw e;
+        }
+        const lines = content.split('\n');
+        const records = [];
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (parsed && typeof parsed === 'object' && typeof parsed.ts === 'string' && typeof parsed.action === 'string') {
+                    records.push(parsed);
+                }
+            }
+            catch {
+                // skip corrupt line
+            }
+        }
+        return records.slice(-limit);
+    }
+}