rakomi 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CRE8EVE Sp. z o.o.
+
+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,24 +1,86 @@
 # rakomi
 
-> **Reserved package name.** This is a placeholder published by **CRE8EVE** to secure
-> the `rakomi` name on the public npm registry.
+The [Rakomi](https://rakomi.com) CLI. EU-native authentication as a service.
 
-The official **Rakomi CLI** is not available under this package yet. When released, the
-CLI will be installable globally:
+## Getting started
 
-```bash
-npm install -g rakomi
+```sh
+npx rakomi login
 ```
 
-Until then, this package only prints a notice if executed.
+Signs you in with your browser (loopback OAuth + PKCE). Add `--no-browser` on a headless/SSH
+session to get a short code to enter on another device instead.
 
-## Why this exists
+## Connect an AI agent
 
-Reserving the unscoped `rakomi` name protects users against typosquatting and
-supply-chain impersonation under the CRE8EVE brand. The organization scope
-[`@rakomi`](https://www.npmjs.com/org/rakomi) is owned separately — owning a scope does
-**not** reserve the matching unscoped name, so this placeholder closes that gap.
+```sh
+npx rakomi connect
+```
+
+Detects Claude Code and writes the `.mcp.json` entry for you, or prints Claude Desktop's
+Custom-Connectors instructions when run with `--client claude-desktop`. Read access works
+immediately once the client finishes its own sign-in; write access is a separate step your
+tenant owner approves — see the [Connect an AI Agent guide](https://docs.rakomi.dev/guides/connect-an-ai-agent).
+
+Pass `--cimd-url <url>` (find it in your MCP client's own connection diagnostics) and `rakomi`
+confirms the connection for you instead of leaving you to check the dashboard; add `--write` to
+also request owner-granted write access once it's found. `--status --cimd-url <url>` re-checks
+later without rewriting `.mcp.json` — the resume path when you weren't ready to approve yet.
+
+## Provision a tenant
+
+```sh
+npx rakomi tenants create "Acme staging"
+```
+
+Creates a new tenant with you as the owner by default (`--owner me`) — no invitation round trip, and
+the response includes a freshly minted API key (shown once — save it). Pass `--owner <email>` to hand
+ownership to someone else instead; that requires a partner API credential (a `client_credentials`
+token), sends a real invitation e-mail, and is refused under `--ci` — see
+[Provision Tenants](https://docs.rakomi.dev/guides/provision-tenants) for both flows end to end.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `login` | sign in (browser by default; `--no-browser` for a device code) |
+| `logout` | clear the local session |
+| `whoami` | show the signed-in account |
+| `connect` | connect Claude Code / Claude Desktop to your tenant (read access) |
+| `tenants create <name>` | create a tenant (`--owner me\|<email>`, `--slug <slug>`) |
+| `tenants list` | list tenants you provisioned |
+
+## Global options
+
+| Option | Meaning |
+| --- | --- |
+| `--json` | machine-readable output |
+| `--yes`, `--ci` | never prompt; fail fast on any step needing a human |
+| `--dry-run` | print what would happen, make no writes or mutating calls |
+| `--no-browser` | use the device-code flow instead of opening a browser |
+| `--no-keychain` | store the session in a `0600` file instead of the OS keychain |
+| `--client <name>` | `claude-code` or `claude-desktop` — required when more than one applies |
+| `--undo` | restore the `.mcp.json` `connect` last backed up |
+| `--cimd-url <url>` | (`connect`) the connecting client's own CIMD document URL — confirms/re-checks the connection |
+| `--status` | (`connect`) re-check status only — needs `--cimd-url`, never rewrites `.mcp.json` |
+| `-h`, `--help` | show help |
+| `-V`, `--version` | print the version |
+
+## Caveats
+
+- **Your session lives in your OS keychain** — macOS Keychain, the Linux Secret Service (via
+  `secret-tool`), or a Data-Protection-API-encrypted file on Windows — whichever is available.
+  `rakomi whoami` names the exact backend in use. When none is available (or you pass
+  `--no-keychain`, or `CI` is set), the CLI falls back to a `0600` file under
+  `~/.config/rakomi/session.json` (or `RAKOMI_CONFIG_DIR` if set) and prints a one-line notice the
+  first time it does. An existing `0600` file from an older install is imported into the keychain
+  automatically, then removed. `rakomi logout` clears whichever backend is in use.
+- **The access token is never printed, logged, or included in `--json` output.**
+- **No telemetry.** The CLI collects nothing and phones home about nothing beyond the Rakomi API
+  calls a command actually needs to make.
+- **`--owner <email>` sends a real invitation e-mail** — it always requires interactive
+  confirmation and is refused under `--ci`.
 
-## Contact
+## License
 
-CRE8EVE — <hello@cre8eve.eu> · https://cre8eve.eu
+[MIT](./LICENSE) © CRE8EVE Sp. z o.o.

package/SECURITY.md

@@ -0,0 +1,206 @@
+# Security Policy
+
+## Supported Versions
+
+This policy covers the four JS-family SDK packages: `@rakomi/node`, `@rakomi/sdk-core`,
+`@rakomi/react`, and `@rakomi/react-native`.
+
+While these packages remain pre-1.0 (`0.x`), they carry **no stability or support guarantee**
+(SemVer 2.0.0 §4); the latest `0.x` line receives security updates on a best-effort basis.
+
+From version **1.0** onward, Rakomi maintains the current (N) and previous (N-1) MAJOR in parallel, with N-1 receiving
+security-only fixes. The CRA support period for each MAJOR is determined in accordance with
+**CRA Art. 13(8)** — at least five years, or the product's expected use time where shorter. The authoritative, machine-readable support windows are published at
+[`https://api.rakomi.com/.well-known/sdk-support.json`](https://api.rakomi.com/.well-known/sdk-support.json)
+and rendered for humans on the [SDK Support & Lifecycle page](https://rakomi.com/sdk-support). This
+document points at that single source rather than re-typing dated rows.
+
+Vulnerabilities in peer dependencies (e.g., React) are out of Rakomi's direct scope, but Rakomi will update minimum peer dependency versions when a peer dependency has a known critical CVE affecting SDK users.
+
+## Reporting a Vulnerability
+
+**Please do NOT open a public GitHub issue for security vulnerabilities.**
+
+We support two reporting channels:
+
+1. **Email:** security@rakomi.com (preferred for initial contact)
+2. **GitHub Private Vulnerability Reporting:** [Submit via GitHub Security](https://github.com/rakomidev/rakomi-js/security/advisories/new) — each report automatically receives a GHSA tracking identifier (GHSA-xxxx-xxxx-xxxx).
+
+For encrypted communication, a PGP public key is available at:
+`https://rakomi.com/rakomi-security-pgp-key.asc`
+
+Include the key fingerprint from this file (section 14) for out-of-band verification when sending encrypted reports.
+
+## Response Targets
+
+We strive to meet these response targets. Actual response times may vary based on issue complexity and team availability.
+
+| Severity | First Response | Fix Target | Disclosure |
+|----------|---------------|------------|------------|
+| Critical (actively exploited) | without undue delay (target: 24h) | 72h patch/mitigation | Designated EU authority notified within 24h (CRA Art. 14) |
+| High | without undue delay (target: 48h) | 14 days | Coordinated after fix |
+| Medium | 5 business days | 90 days | Coordinated after fix |
+| Low | 5 business days | Next release cycle | Changelog note |
+
+Severity is assessed using industry-standard vulnerability scoring criteria.
+
+Rakomi is maintained by a small team. During periods of reduced availability, the auto-reply from security@rakomi.com will confirm receipt and provide the PGP key. For actively exploited vulnerabilities, we will respond as quickly as humanly possible.
+
+## Coordinated Vulnerability Disclosure (CVD) Policy
+
+We follow a coordinated disclosure model with a **90-day embargo** period from the date of acknowledgment. During this time:
+
+- Rakomi will work to develop and release a fix
+- We will keep the reporter updated on progress at least every 7 business days for Critical/High severity issues
+- We will notify the reporter when a fix is released
+- After 90 days, we will publish a security advisory regardless of fix status
+
+We may request an extension if the fix requires significant infrastructure changes, and we will coordinate with the reporter before any deadline extension.
+
+## Safe Harbor
+
+We will not pursue legal action against researchers who follow this disclosure policy and act in good faith. We consider security research conducted in accordance with this policy to be:
+- Conducted lawfully and in good faith under applicable EU law
+- Not subject to legal action by CRE8EVE Sp. z o.o.
+
+Safe harbor **does not extend to**:
+- Accessing or modifying other users' data
+- Performing denial of service attacks
+- Social engineering employees or users
+- Exfiltrating data beyond what is necessary to demonstrate the vulnerability
+- Any activity that violates applicable law
+
+## Scope
+
+**In scope:**
+- `@rakomi/node`, `@rakomi/sdk-core`, `@rakomi/react`, and `@rakomi/react-native` SDK source code and published npm packages
+- Security properties of API interactions initiated by the SDKs (request signing, token verification, credential handling)
+- Authentication flow logic within the SDKs
+
+**Out of scope:**
+- Social engineering attacks against Rakomi employees or users
+- Denial of service attacks
+- Physical security
+- Vulnerabilities in third-party services used by Rakomi's backend
+- Vulnerabilities in peer dependencies (e.g., React) — reported to the relevant maintainer, but Rakomi will update minimum peer dependency versions when a peer dependency has a known critical CVE affecting SDK users
+
+This policy applies to the official `@rakomi/node`, `@rakomi/sdk-core`, `@rakomi/react`, and `@rakomi/react-native` packages distributed via npmjs.com. Forks and derivatives are maintained by their respective authors. Customers in regulated sectors (healthcare, finance) may have additional notification obligations beyond this general policy — contact security@rakomi.com for sector-specific compliance documentation.
+
+## EU Authority Reporting
+
+It is our **policy** to report actively exploited vulnerabilities and severe security incidents
+having an impact on the security of our products to the relevant EU authority in accordance with
+**CRA Art. 14**, on the statutory timeline: an early warning, followed by a fuller notification, and
+a final report.
+
+We report to the national coordinator CSIRT designated for our Member State of main establishment
+(Poland), which is our live reporting channel today; onboarding to the EU single reporting platform
+is in progress, and that platform is the documented onward path as it becomes available to
+manufacturers.
+
+## Security Update Notifications
+
+Consumers of Rakomi SDKs can receive security update notifications through:
+- **GitHub Security Advisories** on this repository (subscribe via GitHub "Watch" → "Security alerts")
+- **npm audit:** `npm audit` or `pnpm audit` will flag known vulnerabilities in installed versions
+
+In accordance with CRA Art. 14(8), after becoming aware of an actively exploited vulnerability or a severe incident having an impact on the security of our products, we will inform impacted users (and, where appropriate, all users) — together with any available risk-mitigation or corrective measures — through the above channels.
+
+## Manufacturer Identification
+
+**Legal entity:** CRE8EVE Sp. z o.o.
+**Registered address:** Tulipanowa 4, 72-003 Dobra, Poland (EU)
+**Contact:** security@rakomi.com (role-based — no personal mailbox or phone is published)
+**Products covered:** `@rakomi/node`, `@rakomi/sdk-core`, `@rakomi/react`, `@rakomi/react-native` (published on npmjs.com)
+
+The manufacturer is itself EU-established (Poland), so no CRA Art. 18 Authorised Representative is required (Art. 18 applies to manufacturers established outside the Union). CRA conformity assessment (Art. 32): these are Class I important products (Annex III). The internal-control procedure (Annex VIII, Module A — manufacturer self-assessment, no notified-body involvement) is available for a Class I product **only where harmonised standards, common specifications, or a European cybersecurity certification scheme at assurance level at least 'substantial' are applied in full** (Art. 32(2)); otherwise a third-party route — EU-type examination plus conformity to type (modules B+C), or full quality assurance (module H) — is required. The applicable route will be confirmed against the harmonised standards in force at the CRA application date. The EU Declaration of Conformity and CE marking attach at the CRA application date (Dec 2027) and are not yet issued. See the full manufacturer record at https://docs.rakomi.dev/compliance/manufacturer/.
+
+## Export Control / Cryptography Notice
+
+The four `@rakomi/*` SDK packages incorporate and invoke cryptography — they verify asymmetric
+digital signatures (JWT/token verification), compare key material in constant time, and rely on the
+host platform's TLS for transport security. They are distributed as **publicly available, mass-market
+software** with cryptographic functionality the end user cannot readily modify.
+
+- **EU — Regulation (EU) 2021/821 (Dual-Use):** the SDKs qualify for the **mass-market** treatment
+  under the Cryptography Note (Note 3) to Category 5, Part 2 of Annex I — generally available to the
+  public, sold without restriction, and not designed for the user to alter the cryptographic
+  functionality. No export authorisation is required for their distribution within or from the EU, and —
+  unlike the US path — the EU decontrol is **self-executing**, with no notification or filing step.
+- **US — Export Administration Regulations (EAR):** the cryptographic functionality is classifiable
+  under **ECCN 5D002**. As **publicly available** open-source software the source code is **not
+  subject to the EAR** (15 CFR §734.7(a)), and the corresponding object code is distributed under the
+  mass-market provisions. The one-time email notification of the public source-code URL to the U.S.
+  BIS and NSA is filed at first public release (15 CFR §742.15(b)).
+
+This notice is provided for transparency and is **not legal advice**. Downstream redistributors are
+responsible for their own export, import, and use obligations in their jurisdiction.
+
+## Post-Market Surveillance
+
+Rakomi monitors SDK health after release through:
+- Automated dependency vulnerability scanning (npm audit, Dependabot)
+- Runtime error patterns derived from API logs (SDK version reported in User-Agent header)
+- Periodic security review of SDK code per the internal security review process
+
+This constitutes the "effective and regular tests and reviews of the security of the product with digital elements" required under CRA Annex I, Part II, point (3). The coordinated-vulnerability-disclosure policy required under CRA Annex I, Part II, point (5) is set out in the "Coordinated Vulnerability Disclosure (CVD) Policy" section above.
+
+## No Bounty Program
+
+Rakomi does not currently operate a paid bug bounty program. We deeply appreciate responsible disclosure and will acknowledge researchers in security advisories (with their consent).
+
+## Reference: security.txt
+
+This policy is referenced in our machine-readable security contact file (RFC 9116):
+`/.well-known/security.txt` — deployed at `https://rakomi.com/.well-known/security.txt`
+
+---
+
+## What to Include in Your Report
+
+*(ISO/IEC 29147:2018 §6.5)*
+
+To help us triage efficiently, please include:
+
+1. **Affected package** name and version (e.g., @rakomi/node 0.2.0)
+2. **Reproduction steps** — a minimal, reproducible example
+3. **Impact assessment** — what an attacker could achieve
+4. **Proof of concept** — if available (do not use real user data)
+5. **Reporter contact** — so we can keep you updated
+
+Reports that do not include reproduction steps or fall outside the defined scope may be closed without a tracking ID.
+
+## Report Tracking
+
+*(ISO/IEC 29147:2018 §6.6)*
+
+Each report receives a unique tracking identifier upon acknowledgment. For reports submitted via GitHub Private Vulnerability Reporting, the GHSA identifier (e.g., GHSA-xxxx-xxxx-xxxx) serves as the tracking ID. For email reports, we will direct you to also submit via GitHub PVR for formal tracking.
+
+## Status Updates
+
+*(ISO/IEC 29147:2018 §6.4)*
+
+We provide status updates at least every **7 business days** for Critical/High severity issues, and upon resolution for Medium/Low severity issues.
+
+## CVE Assignment
+
+Confirmed vulnerabilities with sufficient impact will receive CVE identifiers via GitHub's CNA (CVE Numbering Authority) program.
+
+## Reporter Data Privacy
+
+*(GDPR Art. 6(1)(f) + Art. 13/14)*
+
+Reporter personal data (name, email) is processed under GDPR Art. 6(1)(f) legitimate interest for vulnerability coordination. This data is:
+- Retained for the duration of the vulnerability lifecycle plus 2 years
+- Not shared with third parties except as required for CVE assignment or regulatory reporting (e.g., ENISA, national CSIRT)
+- Accessible to the reporter upon request (GDPR Art. 15)
+- Deletable upon request after vulnerability closure (GDPR Art. 17, where not overridden by regulatory retention obligations)
+
+To exercise your GDPR rights, contact security@rakomi.com.
+
+## PGP Key Fingerprint
+
+The PGP public key for encrypted communication is available at:
+`https://rakomi.com/rakomi-security-pgp-key.asc`
+
+Verify the key fingerprint through an independent channel (e.g., LinkedIn, Twitter/X, or a direct phone call) before sending sensitive information.

package/dist/browser.js

@@ -0,0 +1,15 @@
+import { execFile } from 'node:child_process';
+export function systemBrowserOpener(platform = process.platform) {
+    return (url) => new Promise((resolve) => {
+        const done = () => resolve();
+        if (platform === 'darwin') {
+            execFile('open', [url], done);
+        }
+        else if (platform === 'win32') {
+            execFile('cmd', ['/c', 'start', '""', url], done);
+        }
+        else {
+            execFile('xdg-open', [url], done);
+        }
+    });
+}

package/dist/clients.js

@@ -0,0 +1,24 @@
+export const KNOWN_CLIENTS = ['claude-code', 'claude-desktop'];
+export function isKnownClient(value) {
+    return KNOWN_CLIENTS.includes(value);
+}
+export function clientDisplayName(client) {
+    return client === 'claude-code' ? 'Claude Code' : 'Claude Desktop';
+}
+export function resolveTargetClients(opts) {
+    if (opts.explicitClient) {
+        if (!isKnownClient(opts.explicitClient)) {
+            throw new AmbiguousClientError(`Unknown --client "${opts.explicitClient}". Known clients: ${KNOWN_CLIENTS.join(', ')}.`);
+        }
+        return [opts.explicitClient];
+    }
+    if (opts.claudeCodeDetected)
+        return ['claude-code'];
+    throw new AmbiguousClientError(`Could not detect an installed MCP client automatically. Pass --client <${KNOWN_CLIENTS.join('|')}>.`);
+}
+export class AmbiguousClientError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AmbiguousClientError';
+    }
+}

package/dist/commands/connect.js

@@ -0,0 +1,99 @@
+import { AmbiguousClientError, clientDisplayName, resolveTargetClients } from '../clients.js';
+import { pollCimdMaterialization, requestWriteElevation } from '../connect-client.js';
+import { DEFAULT_MCP_URL } from '../env.js';
+import { InteractiveRequiredError, NotLoggedInError, UsageError } from '../errors.js';
+import { mcpConfigPath, undoMcpConfigWrite, writeRakomiMcpServerEntry } from '../mcp-config.js';
+const CLAUDE_DESKTOP_INSTRUCTIONS = [
+    'Claude Desktop connects to remote MCP servers through Connectors, configured from your Claude',
+    'account rather than a local file — there is nothing for `rakomi connect` to write.',
+    '',
+    '1. Open Settings -> Connectors in Claude Desktop and add a custom connector.',
+    `2. Enter Rakomi's MCP server URL: ${DEFAULT_MCP_URL}`,
+    '3. Click Connect. Claude Desktop opens your browser at accounts.rakomi.com — sign in and',
+    '   approve the read-only consent screen.',
+].join('\n');
+export async function runConnect(deps) {
+    if (deps.undo) {
+        const restored = undoMcpConfigWrite(deps.cwd);
+        deps.stdout.write(restored
+            ? `Restored ${mcpConfigPath(deps.cwd)} from the backup \`rakomi connect\` made.\n`
+            : `No \`rakomi connect\` backup found at ${mcpConfigPath(deps.cwd)}.rakomi-backup — nothing to undo.\n`);
+        return;
+    }
+    const session = deps.session.read();
+    if (!session)
+        throw new NotLoggedInError();
+    if (deps.status) {
+        await reportStatus(deps, session.access_token);
+        return;
+    }
+    let targets;
+    try {
+        targets = resolveTargetClients({ explicitClient: deps.explicitClient, claudeCodeDetected: deps.detectClaudeCode() });
+    }
+    catch (e) {
+        if (e instanceof AmbiguousClientError)
+            throw new UsageError(e.message);
+        throw e;
+    }
+    for (const client of targets) {
+        if (client === 'claude-desktop') {
+            deps.stdout.write(`${clientDisplayName(client)}:\n${CLAUDE_DESKTOP_INSTRUCTIONS}\n`);
+            continue;
+        }
+        await connectClaudeCode(deps, session.access_token);
+    }
+}
+async function reportStatus(deps, accessToken) {
+    if (!deps.cimdUrl) {
+        throw new UsageError('`connect --status` needs `--cimd-url <url>` — the CIMD URL `connect` printed when it started waiting.');
+    }
+    const row = await pollCimdMaterialization(deps, { apiBaseUrl: deps.apiBaseUrl, accessToken, cimdUrl: deps.cimdUrl });
+    if (!row) {
+        deps.stdout.write('Not connected yet — finish sign-in in your MCP client, then run this command again.\n');
+        return;
+    }
+    deps.stdout.write(`Connected — access: ${row.agent_access.level}${row.agent_access.owner_granted ? ' (owner-granted)' : ''}.\n`);
+    if (deps.write && row.agent_access.level !== 'write') {
+        await requestWrite(deps, accessToken, row.id);
+    }
+}
+async function connectClaudeCode(deps, accessToken) {
+    if (deps.dryRun) {
+        deps.stdout.write(`Would write ${mcpConfigPath(deps.cwd)} with mcpServers.rakomi -> ${deps.mcpUrl}. No file written (--dry-run).\n`);
+        return;
+    }
+    const result = writeRakomiMcpServerEntry(deps.cwd, deps.mcpUrl);
+    if (result.wrote) {
+        deps.stdout.write(`Wrote ${mcpConfigPath(deps.cwd)}${result.backedUp ? ' (previous file backed up)' : ''}.\n${result.diff}\n`);
+    }
+    else {
+        deps.stdout.write(`${result.diff}\n`);
+    }
+    deps.stdout.write('Now open Claude Code and run `claude mcp login rakomi` to finish sign-in in your browser.\n' +
+        'Once approved, Claude Code has READ access to your tenant immediately.\n');
+    if (!deps.cimdUrl) {
+        deps.stdout.write('\nOnce connected, Rakomi can confirm it and (with --write) request write access for you — pass ' +
+            '`--cimd-url <url>` (find it in your MCP client\'s own connection diagnostics) to use it, or ' +
+            'check the Agents page in the dashboard.\n');
+        return;
+    }
+    const row = await pollCimdMaterialization(deps, { apiBaseUrl: deps.apiBaseUrl, accessToken, cimdUrl: deps.cimdUrl });
+    if (!row) {
+        deps.stdout.write(`\nNot connected yet. Ctrl+C is safe — resume any time with:\n` +
+            `  rakomi connect --status --cimd-url ${deps.cimdUrl}\n`);
+        return;
+    }
+    deps.stdout.write(`\nConnected — access: ${row.agent_access.level}.\n`);
+    if (deps.write) {
+        if (deps.ci) {
+            throw new InteractiveRequiredError('`connect --write` cannot run under --ci — write-access needs a human owner decision.');
+        }
+        await requestWrite(deps, accessToken, row.id);
+    }
+}
+async function requestWrite(deps, accessToken, oauthClientId) {
+    await requestWriteElevation(deps, { apiBaseUrl: deps.apiBaseUrl, accessToken, oauthClientId });
+    deps.stdout.write("Write-access request sent to your tenant's owner(s) — if that's you, you'll approve it yourself " +
+        'from the dashboard Agents page. Destructive actions will still ask a human every time.\n');
+}

package/dist/commands/login.js

@@ -0,0 +1,70 @@
+import { accountsBaseUrl, apiBaseUrl, clientId as resolveClientId, isCimdClientId } from '../env.js';
+import { CliError, EXIT } from '../errors.js';
+import { buildAuthorizeUrl, exchangeAuthorizationCode } from '../oauth-authcode.js';
+import { loginWithDeviceGrant } from '../oauth-device.js';
+import { generatePkcePair } from '../pkce.js';
+export const LOGIN_SCOPE = 'openid profile email clients:read elevation:request';
+const LOOPBACK_TIMEOUT_MS = 5 * 60_000;
+export async function runLogin(deps) {
+    const apiUrl = apiBaseUrl(deps.env);
+    const cid = resolveClientId(deps.env);
+    if (deps.noBrowser && isCimdClientId(cid)) {
+        throw new CliError('rakomi login --no-browser needs a client registered for the device-code grant; the ' +
+            "default CIMD client_id does not support it. Pass --client <your-client-id> (create one " +
+            'in the dashboard) for headless/SSH sign-in, or omit --no-browser to sign in via loopback.', EXIT.FAIL);
+    }
+    const token = deps.noBrowser
+        ? await runDeviceGrantLogin(deps, apiUrl, cid)
+        : await runLoopbackLogin(deps, apiUrl, cid);
+    const session = {
+        access_token: token.access_token,
+        refresh_token: token.refresh_token,
+        token_type: 'Bearer',
+        expires_at: deps.now() + token.expires_in * 1000,
+        api_base_url: apiUrl,
+        client_id: cid,
+    };
+    deps.session.write(session);
+    deps.stdout.write('Logged in to Rakomi.\n');
+}
+async function runLoopbackLogin(deps, apiUrl, cid) {
+    const listener = await deps.startLoopback();
+    try {
+        const pkce = generatePkcePair();
+        const authorizeUrl = buildAuthorizeUrl({
+            accountsBaseUrl: accountsBaseUrl(deps.env),
+            clientId: cid,
+            redirectUri: listener.redirectUri,
+            pkce,
+            scope: LOGIN_SCOPE,
+        });
+        deps.stdout.write(`Opening your browser to sign in:\n  ${authorizeUrl}\n`);
+        await deps.openBrowser(authorizeUrl);
+        const callback = await listener.waitForCallback(LOOPBACK_TIMEOUT_MS);
+        if (callback.error) {
+            throw new CliError(`Sign-in failed: ${callback.errorDescription ?? callback.error}`, EXIT.FAIL);
+        }
+        if (!callback.code || callback.state !== pkce.state) {
+            throw new CliError('Sign-in callback was missing the authorization code or had a mismatched state.', EXIT.FAIL);
+        }
+        return exchangeAuthorizationCode(deps, {
+            apiBaseUrl: apiUrl,
+            clientId: cid,
+            redirectUri: listener.redirectUri,
+            code: callback.code,
+            codeVerifier: pkce.codeVerifier,
+        });
+    }
+    finally {
+        listener.close();
+    }
+}
+async function runDeviceGrantLogin(deps, apiUrl, cid) {
+    return loginWithDeviceGrant({
+        ...deps,
+        onWaiting: (issued) => {
+            deps.stdout.write(`To sign in, open ${issued.verification_uri} and enter the code ${issued.user_code}\n` +
+                `(or open ${issued.verification_uri_complete} directly).\n`);
+        },
+    }, { apiBaseUrl: apiUrl, clientId: cid, scope: LOGIN_SCOPE });
+}

package/dist/commands/logout.js

@@ -0,0 +1,4 @@
+export function runLogout(deps) {
+    deps.session.clear();
+    deps.stdout.write('Logged out.\n');
+}

package/dist/commands/tenants.js

@@ -0,0 +1,54 @@
+import { InteractiveRequiredError, NotLoggedInError, UsageError } from '../errors.js';
+import { createTenant, listTenants } from '../tenants-client.js';
+export async function runTenantsCreate(deps, args) {
+    const session = deps.session.read();
+    if (!session)
+        throw new NotLoggedInError();
+    const ownerIsSelf = args.owner === 'me';
+    if (!ownerIsSelf && !args.owner.includes('@')) {
+        throw new UsageError(`--owner must be "me" or an e-mail address, got "${args.owner}"`);
+    }
+    if (!ownerIsSelf && deps.ci) {
+        throw new InteractiveRequiredError('`tenants create --owner <email>` (a third-party owner) requires interactive confirmation; use --owner me under --ci.');
+    }
+    if (deps.dryRun) {
+        deps.stdout.write(ownerIsSelf
+            ? `Would create tenant "${args.name}"${args.slug ? ` (slug: ${args.slug})` : ''} with yourself as owner (self-owner — mints an API key). No request sent (--dry-run).\n`
+            : `Would create tenant "${args.name}"${args.slug ? ` (slug: ${args.slug})` : ''} with owner ${args.owner}. No request sent (--dry-run).\n`);
+        return;
+    }
+    const result = await createTenant(deps, {
+        apiBaseUrl: session.api_base_url,
+        accessToken: session.access_token,
+        name: args.name,
+        slug: args.slug,
+        ownerEmail: ownerIsSelf ? undefined : args.owner,
+    });
+    if (deps.json) {
+        deps.stdout.write(JSON.stringify(result) + '\n');
+        return;
+    }
+    const lines = [`Created tenant "${result.tenant.slug}" (${result.tenant.id}) — status: ${result.tenant.status}`];
+    if (result.api_key) {
+        lines.push(`You are the owner. API key (shown ONLY this once — save it now): ${result.api_key.key}`);
+    }
+    else if (result.owner_invitation) {
+        lines.push(`An owner invitation was sent to ${args.owner} (expires ${result.owner_invitation.expires_at}).`);
+    }
+    deps.stdout.write(lines.join('\n') + '\n');
+}
+export async function runTenantsList(deps) {
+    const session = deps.session.read();
+    if (!session)
+        throw new NotLoggedInError();
+    const result = await listTenants(deps, { apiBaseUrl: session.api_base_url, accessToken: session.access_token, parent: 'me' });
+    if (deps.json) {
+        deps.stdout.write(JSON.stringify(result) + '\n');
+        return;
+    }
+    if (result.data.length === 0) {
+        deps.stdout.write('No provisioned tenants.\n');
+        return;
+    }
+    deps.stdout.write(result.data.map((t) => `${t.slug}\t${t.id}\t${t.status}`).join('\n') + '\n');
+}

package/dist/commands/whoami.js

@@ -0,0 +1,18 @@
+import { NotLoggedInError } from '../errors.js';
+import { fetchUserInfo } from '../userinfo-client.js';
+export async function runWhoami(deps) {
+    const session = deps.session.read();
+    if (!session)
+        throw new NotLoggedInError();
+    const info = await fetchUserInfo(deps, { apiBaseUrl: session.api_base_url, accessToken: session.access_token });
+    if (deps.json) {
+        deps.stdout.write(JSON.stringify({ sub: info.sub, email: info.email, org_id: info.org_id, org_role: info.org_role, session_store: deps.session.describePath() }) + '\n');
+        return;
+    }
+    const lines = [`Signed in as: ${info.email ?? info.sub}`];
+    if (info.org_id)
+        lines.push(`Organization: ${info.org_id}${info.org_role ? ` (${info.org_role})` : ''}`);
+    lines.push(`API: ${session.api_base_url}`);
+    lines.push(`Session stored in: ${deps.session.describePath()}`);
+    deps.stdout.write(lines.join('\n') + '\n');
+}

package/dist/connect-client.js

@@ -0,0 +1,32 @@
+import { CliError, EXIT } from './errors.js';
+import { describeError, request } from './http.js';
+export async function pollCimdMaterialization(deps, opts) {
+    const url = new URL('/v1/oauth-clients', opts.apiBaseUrl);
+    url.searchParams.set('cimd_url', opts.cimdUrl);
+    const result = await request(deps, {
+        method: 'GET',
+        url: url.toString(),
+        headers: { authorization: `Bearer ${opts.accessToken}` },
+    });
+    if (result.status === 401) {
+        throw new CliError('Your session has expired. Run `rakomi login` again.', EXIT.NOT_LOGGED_IN);
+    }
+    if (result.status !== 200) {
+        throw new CliError(`Could not check connection status: ${describeError(result.body, result.status)}`, EXIT.FAIL);
+    }
+    return result.body.data[0] ?? null;
+}
+export async function requestWriteElevation(deps, opts) {
+    const result = await request(deps, {
+        method: 'POST',
+        url: `${opts.apiBaseUrl}/v1/oauth-clients/${encodeURIComponent(opts.oauthClientId)}/elevation-requests`,
+        headers: { authorization: `Bearer ${opts.accessToken}` },
+        body: { scopes: ['mcp:tools:write'] },
+    });
+    if (result.status === 401) {
+        throw new CliError('Your session has expired. Run `rakomi login` again.', EXIT.NOT_LOGGED_IN);
+    }
+    if (result.status !== 201 && result.status !== 200) {
+        throw new CliError(`Could not request write access: ${describeError(result.body, result.status)}`, EXIT.FAIL);
+    }
+}