Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(api-keys): let a bearer mint a connector-preset key so the CLI can hand Grok Bot a key that never spends

nirholas3350e513c1d1
diff --git a/api/api-keys.js b/api/api-keys.js
index 1f14d5ad7..872892237 100644
--- a/api/api-keys.js
+++ b/api/api-keys.js
@@ -6,7 +6,8 @@ import { limits, clientIp } from './_lib/rate-limit.js';
import { requireCsrf } from './_lib/csrf.js';
import { parse } from './_lib/validate.js';
import { z } from 'zod';
-import { API_KEY_SCOPES } from './_lib/api-keys.js';
+import { API_KEY_SCOPES, mintApiKey, presetScopes } from './_lib/api-keys.js';
+import { CONNECTOR_MARKER } from './_lib/spend-scope.js';
const ALLOWED_SCOPES = new Set(API_KEY_SCOPES);
@@ -18,6 +19,10 @@ const createSchema = z.object({
.default('avatars:read avatars:write')
.transform((s) => s.trim()),
expires_at: z.string().datetime().optional(),
+ // A named preset replaces `scope`; see KEY_PRESETS in _lib/api-keys.js.
+ // `three-ws setup --client grok-bot` asks for `connector`, the key an AI
+ // agent holds unattended.
+ preset: z.enum(['connector']).optional(),
});
export default wrap(async (req, res) => {
@@ -51,6 +56,8 @@ export default wrap(async (req, res) => {
const body = parse(createSchema, await readJson(req));
+ if (body.preset) return mintPreset(req, res, { userId, bearer, body });
+
// Validate requested scopes are all known
const requestedScopes = body.scope.split(/\s+/).filter(Boolean);
const invalid = requestedScopes.filter((s) => !ALLOWED_SCOPES.has(s));
@@ -93,3 +100,23 @@ export default wrap(async (req, res) => {
// token is returned only on creation — not stored in plaintext
return json(res, 201, { data: { ...row, token } });
});
+
+// A preset key. The preset fixes the scope set and ignores `scope`, so a
+// request can never ask a connector key into carrying a spend scope. A bearer
+// caller still cannot mint beyond its own grant: it gets the preset's scopes
+// it holds, plus the marker that caps the key for as long as it lives.
+async function mintPreset(req, res, { userId, bearer, body }) {
+ const preset = presetScopes(body.preset);
+ const granted = preset.filter((s) => s === CONNECTOR_MARKER || !bearer || hasScope(bearer.scope, s));
+ if (!granted.some((s) => s !== CONNECTOR_MARKER))
+ return error(res, 403, 'insufficient_scope', `this credential holds none of the scopes a ${body.preset} key carries`);
+ const { row, secret } = await mintApiKey({
+ userId,
+ name: body.name,
+ scopes: granted,
+ expiresAt: body.expires_at ?? null,
+ req,
+ via: bearer ? `bearer:${body.preset}` : `session:${body.preset}`,
+ });
+ return json(res, 201, { data: { ...row, token: secret } });
+}
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 94c7964b2..1265e72c8 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -4354,7 +4354,7 @@ or, for an AI agent:
{ "key": { "id": "2c25ec0c-…", "name": "Grok Bot", "prefix": "sk_live_Xb3Q", "scope": "avatars:read … connector", "expires_at": null, "created_at": "…", "secret": "sk_live_…" } }
```
-The `secret` is returned **only once**. Store it immediately; it cannot be retrieved, only replaced. `POST /api/api-keys` takes `{ name, scope, expires_at }` and answers `{ "data": { ..., "token": "sk_live_…" } }`.
+The `secret` is returned **only once**. Store it immediately; it cannot be retrieved, only replaced. `POST /api/api-keys` takes `{ name, scope, expires_at }` and answers `{ "data": { ..., "token": "sk_live_…" } }`. It also takes `preset: "connector"`, which ignores `scope` like `/api/keys` does; a bearer caller gets the connector scopes it holds itself plus the marker, and one holding none of them is refused with `403 insufficient_scope`. `npx three-ws setup --client grok-bot --auth key` mints its key this way ([CLI docs](./cli.md#grok-bot)).
---
diff --git a/tests/api/api-keys.test.js b/tests/api/api-keys.test.js
index 64236e78f..cb57d8e63 100644
--- a/tests/api/api-keys.test.js
+++ b/tests/api/api-keys.test.js
@@ -225,6 +225,46 @@ describe('POST /api/api-keys — create', () => {
});
});
+describe('POST /api/api-keys with preset connector', () => {
+ const row = (scope) => [{ id: 'kc', name: 'Grok Bot', prefix: 'sk_live_conn', scope, expires_at: null, created_at: '2026-10-09T00:00:00Z' }];
+ const inserted = () => sqlState.calls.find((c) => /insert into api_keys/i.test(c.query));
+
+ it('mints the whole connector set for a browser session', async () => {
+ authState.session = { id: 'user-c1' };
+ sqlState.queue.push(row('avatars:read avatars:write agents:read agents:write memory:read memory:write connector'));
+ const { status, body } = await invoke({ method: 'POST', body: { name: 'Grok Bot', preset: 'connector' } });
+ expect(status).toBe(201);
+ expect(body.data.token).toMatch(/^sk_live_/);
+ expect(inserted().values).toContain('avatars:read avatars:write agents:read agents:write memory:read memory:write connector');
+ });
+
+ it('gives a bearer only the connector scopes it holds, plus the marker', async () => {
+ authState.bearer = { userId: 'user-c2', scope: 'offline_access profile avatars:read avatars:write memory:read memory:write agents:read wallet:read wallet:write', source: 'oauth' };
+ sqlState.queue.push(row('avatars:read avatars:write agents:read memory:read memory:write connector'));
+ const { status } = await invoke({ method: 'POST', body: { name: 'Grok Bot', preset: 'connector' } });
+ expect(status).toBe(201);
+ const scope = inserted().values.find((v) => typeof v === 'string' && v.includes('connector'));
+ expect(scope.split(' ').sort()).toEqual(['agents:read', 'avatars:read', 'avatars:write', 'connector', 'memory:read', 'memory:write']);
+ expect(scope).not.toMatch(/wallet|services|profile/);
+ });
+
+ it('ignores a scope sent beside the preset, so a connector key never carries a spend scope', async () => {
+ authState.session = { id: 'user-c3' };
+ sqlState.queue.push(row('x'));
+ await invoke({ method: 'POST', body: { name: 'Grok Bot', preset: 'connector', scope: 'wallet:write services:write' } });
+ const scope = inserted().values.find((v) => typeof v === 'string' && v.includes('connector'));
+ expect(scope).not.toMatch(/wallet:write|services:write/);
+ });
+
+ it('refuses a bearer that holds none of the connector scopes', async () => {
+ authState.bearer = { userId: 'user-c4', scope: 'profile wallet:read', source: 'oauth' };
+ const { status, body } = await invoke({ method: 'POST', body: { name: 'Grok Bot', preset: 'connector' } });
+ expect(status).toBe(403);
+ expect(body.error).toBe('insufficient_scope');
+ expect(inserted()).toBeUndefined();
+ });
+});
+
describe('method routing', () => {
it('rejects PUT with 405', async () => {
const { status, body } = await invoke({ method: 'PUT' });