@rakomi/node 0.0.0 → 0.1.0

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,3 +1,59 @@
 # @rakomi/node
 
-Name reserved. The first stable release is published with build provenance from rakomidev/rakomi-js.
+Server-side Node.js SDK for [Rakomi](https://rakomi.com) — EU-native auth-as-a-service.
+
+**Intended purpose & user:** for backend developers verifying Rakomi access tokens and webhook
+signatures in a trusted Node.js runtime.
+
+- **1 runtime dependency** — only [`jose`](https://github.com/panva/jose) for JWT/JWKS operations.
+- **ESM-first** — ships as ES modules; CJS supported via Node.js `require(esm)`.
+- **Result pattern** — `verifyToken()` / `verifyWebhook()` never throw; they return
+  `{ ok: true, data }` or `{ ok: false, error }`.
+- **Type-safe** — full TypeScript types with generic payload support.
+
+## Install
+
+```bash
+pnpm add @rakomi/node
+```
+
+Requires **Node.js 22+**.
+
+## Quick start
+
+```typescript
+import { RakomiClient } from '@rakomi/node';
+
+const rakomi = new RakomiClient({
+  apiKey: 'akm_live_xxx', // akm_test_* in development
+});
+
+const result = await rakomi.verifyToken(token);
+if (result.ok) {
+  console.log('User ID:', result.data.userId);
+} else {
+  console.error('Error:', result.error.code);
+}
+```
+
+API keys must start with `akm_live_` (production) or `akm_test_` (testing).
+
+## Secure defaults
+
+Token signatures are verified with a fixed asymmetric algorithm (never read from the token header),
+the signing-key set is fetched only from the pinned issuer host, and issuer/audience/expiry are
+enforced. See the [Secure defaults](https://docs.rakomi.dev/sdk/secure-defaults/) guide.
+
+## Documentation
+
+- [SDK reference](https://docs.rakomi.dev/sdk/) · [Quickstart](https://docs.rakomi.dev/getting-started/quickstart-sdk/)
+- [Error codes](https://docs.rakomi.dev/sdk/errors/)
+
+## Security & support
+
+- Vulnerability reporting and the coordinated-disclosure policy: [`SECURITY.md`](./SECURITY.md).
+- Dated support windows (CRA Art. 13(8)): [SDK Support & Lifecycle](https://rakomi.com/sdk-support).
+
+## License
+
+See [`LICENSE`](./LICENSE).

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://rakomi.com/.well-known/sdk-support.json`](https://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/agents.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Node SDK surface for end-user agent management.
+ *
+ * Wraps the two `/v1/users/me/agents*` endpoints:
+ * - `GET /v1/users/me/agents` → `list({ userToken })`
+ * - `DELETE /v1/users/me/agents/{agentClientId}` → `revoke({ userToken, agentClientId })`
+ *
+ * These endpoints require an end-user JWT (NOT an API key), so each helper
+ * takes a `{ userToken }` option. The SDK client (constructed with an API key)
+ * only carries the `baseUrl`; the user token flows per-call.
+ *
+ * Tenant-admin agent management is intentionally out of scope: the SDK is
+ * consumed BY agents and end users, not by tenant admins managing agents.
+ */
+import type { VerifyResult } from './types.js';
+/**
+ * End-user-side agent row returned by `GET /v1/users/me/agents`.
+ */
+export type UserAgentResponse = {
+    agent_client_id: string;
+    agent_name: string;
+    agent_logo_url?: string;
+    agent_class?: string;
+    last_action_at?: string;
+    action_count: number;
+    revoked_at?: string;
+    agent_revoked_at?: string;
+};
+export interface AgentsClientContext {
+    baseUrl: string;
+    fetchImpl?: typeof fetch;
+}
+export interface AgentsCallOptions {
+    /** End-user JWT (Bearer). REQUIRED — these endpoints do NOT accept API keys. */
+    userToken: string;
+}
+export interface ListUserAgentsResponse {
+    data: UserAgentResponse[];
+}
+export interface RevokeUserAgentOptions extends AgentsCallOptions {
+    /** The agent's public `client_id` (matches `oauth_clients.client_id`). */
+    agentClientId: string;
+}
+export interface RevokeUserAgentResponse {
+    agent_client_id: string;
+    revoked_at: string;
+    reason: string;
+}
+export declare class AgentsNetworkError extends Error {
+    readonly code = "agents/network_error";
+    constructor(message: string);
+}
+export declare class AgentNotFoundError extends Error {
+    readonly code = "agents/not_found";
+    constructor(message?: string);
+}
+export declare class AgentsUnauthorizedError extends Error {
+    readonly code = "agents/unauthorized";
+    constructor(message?: string);
+}
+export declare class AgentsRateLimitedError extends Error {
+    readonly code = "agents/rate_limited";
+    readonly retryAfterSeconds?: number;
+    constructor(retryAfterSeconds?: number);
+}
+/**
+ * User-scoped agents resource. Attached to `RakomiClient#users.me.agents`.
+ *
+ * All methods require an end-user JWT passed via `{ userToken }`. The underlying
+ * `RakomiClient` API key is NOT sent on these calls — the API rejects API-key
+ * auth on user-scoped routes.
+ *
+ * SSRF hardening: every `fetch` uses `redirect: 'error'`.
+ */
+export declare class AgentsClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(ctx: AgentsClientContext);
+    /**
+     * GET /v1/users/me/agents — list every agent that has ever acted on the
+     * authenticated user's behalf, with per-user + per-tenant revocation status.
+     */
+    list(options: AgentsCallOptions): Promise<VerifyResult<ListUserAgentsResponse>>;
+    /**
+     * DELETE /v1/users/me/agents/{agentClientId} — revoke an agent from acting
+     * on this user's behalf (GDPR Art. 7(3)). Idempotent — re-revoking returns
+     * 200 with the existing row and fires no second audit/webhook.
+     */
+    revoke(options: RevokeUserAgentOptions): Promise<VerifyResult<RevokeUserAgentResponse>>;
+}

package/dist/agents.js

@@ -0,0 +1,203 @@
+/**
+ * Node SDK surface for end-user agent management.
+ *
+ * Wraps the two `/v1/users/me/agents*` endpoints:
+ * - `GET /v1/users/me/agents` → `list({ userToken })`
+ * - `DELETE /v1/users/me/agents/{agentClientId}` → `revoke({ userToken, agentClientId })`
+ *
+ * These endpoints require an end-user JWT (NOT an API key), so each helper
+ * takes a `{ userToken }` option. The SDK client (constructed with an API key)
+ * only carries the `baseUrl`; the user token flows per-call.
+ *
+ * Tenant-admin agent management is intentionally out of scope: the SDK is
+ * consumed BY agents and end users, not by tenant admins managing agents.
+ */
+export class AgentsNetworkError extends Error {
+    code = 'agents/network_error';
+    constructor(message) {
+        super(message);
+        this.name = 'AgentsNetworkError';
+    }
+}
+export class AgentNotFoundError extends Error {
+    code = 'agents/not_found';
+    constructor(message = 'Agent not found in this tenant') {
+        super(message);
+        this.name = 'AgentNotFoundError';
+    }
+}
+export class AgentsUnauthorizedError extends Error {
+    code = 'agents/unauthorized';
+    constructor(message = 'Missing or invalid user token') {
+        super(message);
+        this.name = 'AgentsUnauthorizedError';
+    }
+}
+export class AgentsRateLimitedError extends Error {
+    code = 'agents/rate_limited';
+    retryAfterSeconds;
+    constructor(retryAfterSeconds) {
+        super('Rate limit exceeded for /v1/users/me/agents');
+        this.name = 'AgentsRateLimitedError';
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+async function safeJson(res) {
+    try {
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+function parseRetryAfter(res) {
+    const v = res.headers.get('retry-after');
+    if (!v)
+        return undefined;
+    const n = Number(v);
+    if (Number.isFinite(n) && n > 0)
+        return Math.round(n);
+    return undefined;
+}
+function networkError(message) {
+    return {
+        code: 'agents/network_error',
+        message,
+        suggestion: 'Verify Rakomi base URL is reachable and that DNS / TLS is healthy.',
+        docs_url: 'https://docs.rakomi.dev/guides/ai-agents',
+    };
+}
+function notFoundError() {
+    return {
+        code: 'agents/not_found',
+        message: 'Agent not found in this tenant',
+        suggestion: 'Verify the agentClientId matches an agent that has acted on this user before.',
+        docs_url: 'https://docs.rakomi.dev/guides/ai-agents',
+    };
+}
+function unauthorizedError() {
+    return {
+        code: 'agents/unauthorized',
+        message: 'Missing or invalid user token',
+        suggestion: 'Pass a valid end-user JWT in `userToken`. API keys are NOT accepted on /v1/users/me routes.',
+        docs_url: 'https://docs.rakomi.dev/guides/ai-agents',
+    };
+}
+function rateLimitedError(retryAfter) {
+    return {
+        code: 'agents/rate_limited',
+        message: 'Rate limit exceeded for /v1/users/me/agents',
+        suggestion: retryAfter !== undefined
+            ? `Wait ${retryAfter}s and retry.`
+            : 'Slow down and retry after a short back-off.',
+        docs_url: 'https://docs.rakomi.dev/guides/ai-agents',
+    };
+}
+function genericError(status, body) {
+    return {
+        code: body?.code ?? `agents/http_${status}`,
+        message: body?.message ?? `HTTP ${status}`,
+        suggestion: 'Inspect the response body and retry if appropriate.',
+        docs_url: 'https://docs.rakomi.dev/guides/ai-agents',
+    };
+}
+/**
+ * User-scoped agents resource. Attached to `RakomiClient#users.me.agents`.
+ *
+ * All methods require an end-user JWT passed via `{ userToken }`. The underlying
+ * `RakomiClient` API key is NOT sent on these calls — the API rejects API-key
+ * auth on user-scoped routes.
+ *
+ * SSRF hardening: every `fetch` uses `redirect: 'error'`.
+ */
+export class AgentsClient {
+    baseUrl;
+    fetchImpl;
+    constructor(ctx) {
+        this.baseUrl = ctx.baseUrl;
+        this.fetchImpl = ctx.fetchImpl ?? fetch;
+    }
+    /**
+     * GET /v1/users/me/agents — list every agent that has ever acted on the
+     * authenticated user's behalf, with per-user + per-tenant revocation status.
+     */
+    async list(options) {
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}/v1/users/me/agents`, {
+                method: 'GET',
+                redirect: 'error',
+                headers: {
+                    Authorization: `Bearer ${options.userToken}`,
+                    Accept: 'application/json',
+                },
+            });
+        }
+        catch (err) {
+            return { ok: false, error: networkError(err?.message ?? 'Network error') };
+        }
+        if (res.status === 200) {
+            const body = await safeJson(res);
+            if (!body || !Array.isArray(body.data)) {
+                return { ok: false, error: networkError('Malformed response body — expected { data: UserAgentResponse[] }') };
+            }
+            return { ok: true, data: body };
+        }
+        if (res.status === 401)
+            return { ok: false, error: unauthorizedError() };
+        if (res.status === 429)
+            return { ok: false, error: rateLimitedError(parseRetryAfter(res)) };
+        const body = await safeJson(res);
+        return { ok: false, error: genericError(res.status, body) };
+    }
+    /**
+     * DELETE /v1/users/me/agents/{agentClientId} — revoke an agent from acting
+     * on this user's behalf (GDPR Art. 7(3)). Idempotent — re-revoking returns
+     * 200 with the existing row and fires no second audit/webhook.
+     */
+    async revoke(options) {
+        if (!options.agentClientId) {
+            return {
+                ok: false,
+                error: {
+                    code: 'agents/invalid_request',
+                    message: 'agentClientId is required',
+                    suggestion: 'Pass the agent\'s public client_id (matches oauth_clients.client_id).',
+                    docs_url: 'https://docs.rakomi.dev/guides/ai-agents',
+                },
+            };
+        }
+        let res;
+        try {
+            res = await this.fetchImpl(`${this.baseUrl}/v1/users/me/agents/${encodeURIComponent(options.agentClientId)}`, {
+                method: 'DELETE',
+                redirect: 'error',
+                headers: {
+                    Authorization: `Bearer ${options.userToken}`,
+                    Accept: 'application/json',
+                },
+            });
+        }
+        catch (err) {
+            return { ok: false, error: networkError(err?.message ?? 'Network error') };
+        }
+        if (res.status === 200) {
+            const body = await safeJson(res);
+            if (!body ||
+                typeof body.agent_client_id !== 'string' ||
+                typeof body.revoked_at !== 'string' ||
+                typeof body.reason !== 'string') {
+                return { ok: false, error: networkError('Malformed response body — expected { agent_client_id, revoked_at, reason }') };
+            }
+            return { ok: true, data: body };
+        }
+        if (res.status === 401)
+            return { ok: false, error: unauthorizedError() };
+        if (res.status === 404)
+            return { ok: false, error: notFoundError() };
+        if (res.status === 429)
+            return { ok: false, error: rateLimitedError(parseRetryAfter(res)) };
+        const body = await safeJson(res);
+        return { ok: false, error: genericError(res.status, body) };
+    }
+}

package/dist/anonymous.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Node SDK surface for anonymous sign-ins.
+ *
+ * Pure server-side: no browser globals (window/document/navigator/localStorage).
+ * Browser apps should use the React hook `useAnonymousSignin` from `@rakomi/react`
+ * which calls this under the hood via the user's backend, OR hit `/v1/auth/anonymous`
+ * directly from the browser with the tenant's public API key.
+ *
+ * Returns a Result shape consistent with the rest of the SDK: NEVER throws on
+ * expected API errors (403/429/402/401), throws ONLY on programmer errors.
+ */
+import { RakomiError } from './errors.js';
+import { AnonymousSessionExpiredError } from './errors.js';
+import type { VerifyResult } from './types.js';
+export interface AnonymousSigninOptions {
+    /** Optional tenant-supplied public metadata (≤1 KB JSON, same rules as). */
+    publicMetadata?: Record<string, unknown>;
+}
+export interface AnonymousSigninResult {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+    user: {
+        id: string;
+        isAnonymous: true;
+        createdAt: string;
+    };
+}
+export interface AnonymousSigninCallContext {
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * POST /v1/auth/anonymous. Returns Result — never throws on 4xx.
+ */
+export declare function anonymousSignin(ctx: AnonymousSigninCallContext, options?: AnonymousSigninOptions): Promise<VerifyResult<AnonymousSigninResult>>;
+/**
+ * Decode an access token's `is_anonymous` claim WITHOUT verifying the signature.
+ * Used only to gate the `AnonymousSessionExpiredError` path — callers should still
+ * verify any trust-sensitive claim via `client.verifyToken()`.
+ */
+export declare function isAnonymousTokenHeuristic(accessToken: string): boolean;
+/**
+ * Classify a refresh failure: if the prior token was anonymous and the refresh
+ * returned 401, throw `AnonymousSessionExpiredError`. Otherwise the caller
+ * decides its own UX routing.
+ */
+export declare function maybeThrowAnonymousExpired(priorAccessToken: string | null, refreshStatus: number): void;
+export { AnonymousSessionExpiredError, RakomiError };