From 50f485c42e21aacd19be77141ec55d8525e6f13e Mon Sep 17 00:00:00 2001 From: "Paul K." Date: Wed, 18 Nov 2026 22:22:42 -0500 Subject: [PATCH] feat(list): show the person's own level beside the key's access, by level (v2.15.0) Co-authored-by: Claude Opus 5.5 --- README.md | 8 ++- package-lock.json | 4 +- package.json | 2 +- skills/one/SKILL.md | 6 +- src/commands/connection.ts | 41 +++++++++---- src/lib/access.test.ts | 58 ++++++++++++++++--- src/lib/access.ts | 101 +++++++++++++++++++++++++++++---- src/lib/api-own-access.test.ts | 22 +++++++ src/lib/api.ts | 25 ++++++++ src/lib/guide-content.ts | 8 ++- src/lib/types.ts | 18 +++++- 11 files changed, 250 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index aea0cfa..a14d9d0 100644 --- a/README.md +++ b/README.md @@ -208,7 +208,7 @@ You need the connection key (rightmost column) when executing actions. | Policy | Means | `level` | |--------|-------|---------| | `{"policy": "full"}` | Every action on the connection | `full` (Full access) | -| `{"policy": "methods", "methods": ["GET"]}` | Only actions with those methods | `read-only`, `read-write` (GET, POST, PUT, PATCH), or `custom` | +| `{"policy": "methods", "methods": ["GET"], "access": ["read"]}` | Only actions at the levels in `access` (GET is `read`, POST/PUT/PATCH `write`, DELETE `delete`); One judges an action by its level, not its method | `read-only`, `write-only`, `read-write`, `full` (all three levels), or `custom` | | `{"policy": "actions", "actions": [{"actionId": "...", "title": "...", "method": "..."}]}` | Only these specific actions | `custom`, or `none` when empty | A connection the key does not reach is not listed. When the policy is `actions`, those actions are exactly what may run — `actions load ` reads their docs, no find needed. @@ -223,13 +223,17 @@ A connection the key does not reach is not listed. When the policy is `actions`, "platform": "gmail", "state": "operational", "key": "live::gmail::default::abc123", - "access": { "policy": "methods", "methods": ["GET"], "level": "read-only" } + "access": { "policy": "full", "level": "full" }, + "viewerAccessLevel": "read", + "effectiveLevel": "read-only" } ], "accessSource": "server" } ``` +**Your own level.** In an organization, an admin may share an app with you at a lower level, or cap it with App Controls. The CLI reads that level from `GET /v1/connections` and reports it as `viewerAccessLevel` (`none`, `read`, `write`, `read_write`, `full`, `custom`). One holds every call to both it and `access`; `effectiveLevel` names what the two leave together. The human table adds a "Your level" column, in the dashboard's words, when any connection holds you below Full access. An older API sends no level, and the listing stays as it was. + `accessSource` is `"server"` when One reported the key's access and `"local"` when it could not (an older API); then `access` shows only the CLI's own settings, the human table labels the column "Access (CLI settings only)", and `accessHint` says One may allow less. `knowledgeOnly: true` appears when knowledge-only mode is on (execution disabled), and `unresolvedActionIds` lists action ids that could not be looked up. This mirrors the `access` field on the One MCP server's `list_one_integrations` tool, so both surfaces report access the same way. diff --git a/package-lock.json b/package-lock.json index 20856d1..aac5370 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@withone/cli", - "version": "2.14.15", + "version": "2.15.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@withone/cli", - "version": "2.14.15", + "version": "2.15.0", "dependencies": { "@clack/prompts": "^0.9.1", "commander": "^13.1.0", diff --git a/package.json b/package.json index 1207af0..297b8bb 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@withone/cli", - "version": "2.14.15", + "version": "2.15.0", "description": "CLI for managing One", "type": "module", "files": [ diff --git a/skills/one/SKILL.md b/skills/one/SKILL.md index 2914e0d..0ff1eb7 100644 --- a/skills/one/SKILL.md +++ b/skills/one/SKILL.md @@ -47,14 +47,16 @@ Always follow this sequence when the user wants to do something on a connected p one --agent connection list ``` -Returns connected platforms with their connection keys (needed for execution), platform names in kebab-case (needed for finding actions), and an `access` field per connection telling you what you may run there. `access` is what One enforces for this key (the choices made on the consent page, or later in the dashboard), narrowed by any limits set with `one config`; `access.level` names it the way the consent page does: `full`, `read-write`, `read-only`, `custom` or `none`. When telling the user their access, use those words (Full access, Read & write, Read only, Custom, No access). +Returns connected platforms with their connection keys (needed for execution), platform names in kebab-case (needed for finding actions), and an `access` field per connection telling you what you may run there. `access` is what One enforces for this key (the choices made on the consent page, or later in the dashboard), narrowed by any limits set with `one config`; `access.level` names it the way the consent page does: `full`, `read-write`, `read-only`, `write-only`, `custom` or `none`. When telling the user their access, use those words (Full access, Read & write, Read only, Write only, Custom, No access). + +In an organization, a connection may also carry `viewerAccessLevel`: the most the user may run through it, set by their share or the organization's App Controls (`none`, `read`, `write`, `read_write`, `full`, `custom`). One holds every call to both it and `access`, and `effectiveLevel` names what that leaves. Plan by `effectiveLevel`; when it is below `access.level`, tell the user their share or App Controls limit it, not the key. **Read `access` before you plan a workflow** — it saves you from discovering a restriction as a 403 halfway through: | `access` | What it means | |----------|---------------| | `{"policy": "full"}` | Every action on this connection is available | -| `{"policy": "methods", "methods": ["GET"]}` | Only actions with these HTTP methods will execute — don't propose writes | +| `{"policy": "methods", "methods": ["GET"], "access": ["read"]}` | Only actions at the levels in `access` will execute — here reads, so don't propose writes. One judges an action by what it does, not its HTTP method: a POST search is a `read` | | `{"policy": "actions", "actions": [...]}` | Only these exact actions may run. Each has `actionId`, `title`, `method` — **use them directly**: `actions load ` reads their docs, no find needed | `accessSource` is `"server"` when One reported the key's access, or `"local"` when it could not (the `accessHint` says so) — then `access` reflects only this CLI's settings and One may allow less: tell the user it is unverified rather than calling it full access. diff --git a/src/commands/connection.ts b/src/commands/connection.ts index f1cffd6..5d097a6 100644 --- a/src/commands/connection.ts +++ b/src/commands/connection.ts @@ -11,12 +11,14 @@ import { intersectEnvelopes, envelopeToAccess, accessLevel, + heldLevel, + viewerLevelLabel, } from '../lib/access.js'; import { openConnectionPage, getConnectionUrl, type ConnectionUrlParams } from '../lib/browser.js'; import { findPlatform, findSimilarPlatforms } from '../lib/platforms.js'; import { printTable } from '../lib/table.js'; import * as output from '../lib/output.js'; -import type { AccessLevel, Connection, ConnectionAccess, KeyAccessDocument, PermissionLevel } from '../lib/types.js'; +import type { AccessLevel, Connection, ConnectionAccess, KeyAccessDocument, PermissionLevel, ViewerAccessLevel } from '../lib/types.js'; export async function connectionAddCommand(platformArg?: string, options?: { tag?: string }): Promise { if (output.isAgentMode()) { @@ -187,12 +189,15 @@ export async function connectionListCommand(options?: { search?: string; limit?: // dashboard's access editor), fetched beside the listing. An API that // does not answer it yet leaves the CLI's own settings as the only source, // and says so. - const [allConnections, serverAccess] = await Promise.all([ + // The person's own level (their share, or App Controls) caps every call + // too; an older backend sends none, which leaves the listing as it was. + const [allConnections, serverAccess, viewerLevels] = await Promise.all([ api.listConnections(), api.getOwnAccess().then( doc => ({ ok: true as const, doc }), () => ({ ok: false as const, doc: null }), ), + api.listViewerLevels().catch(() => new Map()), ]); // The CLI's own access settings (`one config`) narrow it further. @@ -235,14 +240,19 @@ export async function connectionListCommand(options?: { search?: string; limit?: total: filtered.length, showing: limited.length, ...(searchQuery && { search: searchQuery }), - connections: limited.map(conn => ({ - platform: conn.platform, - state: conn.state, - key: conn.key, - ...(conn.name && { name: conn.name }), - ...(conn.tags?.length && { tags: conn.tags }), - access: withLevel(accessFor(conn)), - })), + connections: limited.map(conn => { + const access = accessFor(conn); + const viewer = viewerLevels.get(conn.key); + return { + platform: conn.platform, + state: conn.state, + key: conn.key, + ...(conn.name && { name: conn.name }), + ...(conn.tags?.length && { tags: conn.tags }), + access: withLevel(access), + ...(viewer && { viewerAccessLevel: viewer, effectiveLevel: heldLevel(access, viewer) }), + }; + }), accessSource: serverAccess.ok ? 'server' : 'local', ...(knowledgeOnly && { knowledgeOnly: true }), ...(unresolved.size > 0 && { unresolvedActionIds: [...unresolved] }), @@ -290,9 +300,12 @@ export async function connectionListCommand(options?: { search?: string; limit?: key: conn.key, tags: conn.tags?.length ? conn.tags.join(', ') : '', access: formatAccess(accessFor(conn)), + viewer: viewerLevelLabel(viewerLevels.get(conn.key) ?? 'full'), })); const hasTags = rows.some(r => r.tags); + // Only when something holds the person below the key; otherwise every row reads Full access. + const isHeld = displayed.some(conn => (viewerLevels.get(conn.key) ?? 'full') !== 'full'); printTable( [ @@ -302,10 +315,18 @@ export async function connectionListCommand(options?: { search?: string; limit?: { key: 'key', label: 'Connection Key', color: pc.dim }, ...(hasTags ? [{ key: 'tags', label: 'Tags', color: pc.dim }] : []), { key: 'access', label: serverAccess.ok ? 'Access' : 'Access (CLI settings only)', color: pc.yellow }, + ...(isHeld ? [{ key: 'viewer', label: 'Your level', color: pc.yellow }] : []), ], rows ); + if (isHeld) { + p.note( + wrapText('Your level is what your share or App Controls let you do through a connection. One holds every call to both it and Access.'), + 'Your level' + ); + } + console.log(); if (hintText || unresolved.size > 0) { diff --git a/src/lib/access.test.ts b/src/lib/access.test.ts index def5e69..162b848 100644 --- a/src/lib/access.test.ts +++ b/src/lib/access.test.ts @@ -3,8 +3,12 @@ import assert from 'node:assert/strict'; import fs from 'node:fs'; import os from 'node:os'; import path from 'node:path'; -import { computeConnectionAccess, formatAccess, resolveAllowedActions } from './access.js'; -import type { ActionDetails, ResolvedAllowedAction } from './types.js'; +import { computeConnectionAccess, envelopeToAccess, formatAccess, heldLevel, resolveAllowedActions } from './access.js'; +import type { ActionDetails, ConnectionAccess, ResolvedAllowedAction } from './types.js'; + +/** A method-scoped access, as `one list` builds it. */ +const methods = (list: string[]): ConnectionAccess => + envelopeToAccess({ reachable: true, methods: list, actionIds: null }, []).access; import { setHomeTo, snapshotHomeEnv, restoreHomeEnv, type HomeEnvSnapshot } from '../test-support/home.js'; const granted: ResolvedAllowedAction[] = [ @@ -24,11 +28,11 @@ describe('computeConnectionAccess', () => { it('reports the method set for a non-admin permission level', () => { assert.deepEqual( computeConnectionAccess('gmail', 'read', ['*'], []), - { policy: 'methods', methods: ['GET'] } + { policy: 'methods', methods: ['GET'], access: ['read'] } ); assert.deepEqual( computeConnectionAccess('gmail', 'write', ['*'], []), - { policy: 'methods', methods: ['GET', 'POST', 'PUT', 'PATCH'] } + { policy: 'methods', methods: ['GET', 'POST', 'PUT', 'PATCH'], access: ['read', 'write'] } ); }); @@ -52,13 +56,20 @@ describe('computeConnectionAccess', () => { describe('formatAccess', () => { it('renders each policy for the table', () => { assert.equal(formatAccess({ policy: 'full' }), 'Full access'); - assert.equal(formatAccess({ policy: 'methods', methods: ['GET'] }), 'Read only'); - assert.equal(formatAccess({ policy: 'methods', methods: ['GET', 'POST', 'PUT', 'PATCH'] }), 'Read & write'); - assert.equal(formatAccess({ policy: 'methods', methods: ['GET', 'POST'] }), 'GET, POST'); - assert.equal(formatAccess({ policy: 'methods', methods: [] }), 'No access'); + assert.equal(formatAccess(methods(['GET'])), 'Read only'); + assert.equal(formatAccess(methods(['GET', 'POST', 'PUT', 'PATCH'])), 'Read & write'); + assert.equal(formatAccess(methods([])), 'No access'); assert.equal(formatAccess({ policy: 'actions', actions: [] }), 'No access'); }); + it('names methods by the levels they stand for, as One judges them', () => { + assert.equal(formatAccess(methods(['GET', 'POST'])), 'Read & write'); + assert.equal(formatAccess(methods(['POST'])), 'Write only'); + assert.equal(formatAccess(methods(['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])), 'Full access'); + assert.equal(formatAccess(methods(['GET', 'DELETE'])), 'Read, Delete'); + assert.equal(formatAccess(methods(['HEAD'])), 'No access'); + }); + it('truncates long action lists', () => { const actions = granted.map(({ actionId, title, method }) => ({ actionId, title, method })); assert.equal( @@ -68,6 +79,37 @@ describe('formatAccess', () => { }); }); +describe('heldLevel', () => { + const full: ConnectionAccess = { policy: 'full' }; + const send: ConnectionAccess = { policy: 'actions', actions: [{ actionId: 'a1', title: 'Send Email', method: 'POST' }] }; + + it('is the key\'s level when nothing holds the person, or an older API sent no level', () => { + assert.equal(heldLevel(full, undefined), 'full'); + assert.equal(heldLevel(full, 'full'), 'full'); + assert.equal(heldLevel(methods(['GET']), 'full'), 'read-only'); + }); + + it('holds a full key to a lower share', () => { + assert.equal(heldLevel(full, 'read'), 'read-only'); + assert.equal(heldLevel(full, 'read_write'), 'read-write'); + assert.equal(heldLevel(full, 'write'), 'write-only'); + assert.equal(heldLevel(full, 'none'), 'none'); + }); + + it('is the lower of the key and the share', () => { + assert.equal(heldLevel(methods(['GET']), 'read_write'), 'read-only'); + assert.equal(heldLevel(methods(['GET', 'POST', 'PUT', 'PATCH']), 'read'), 'read-only'); + assert.equal(heldLevel(methods(['POST']), 'read'), 'none'); + }); + + it('stays custom where a level cannot name the actions', () => { + assert.equal(heldLevel(full, 'custom'), 'custom'); + assert.equal(heldLevel(send, 'read'), 'custom'); + assert.equal(heldLevel(send, 'none'), 'none'); + assert.equal(heldLevel(methods([]), 'custom'), 'none'); + }); +}); + // resolveAllowedActions goes through the on-disk knowledge cache, so sandbox // $HOME to a temp dir instead of touching the developer's real ~/.one/. describe('resolveAllowedActions', () => { diff --git a/src/lib/access.ts b/src/lib/access.ts index 48b5fc6..1b4984a 100644 --- a/src/lib/access.ts +++ b/src/lib/access.ts @@ -17,10 +17,12 @@ import { PERMISSION_METHODS } from './api.js'; import { resolveActionDetails } from './action-details.js'; import type { AccessLevel, + ActionLevel, ConnectionAccess, KeyAccessDocument, PermissionLevel, ResolvedAllowedAction, + ViewerAccessLevel, } from './types.js'; /** @@ -84,7 +86,7 @@ export function computeConnectionAccess( const methods = PERMISSION_METHODS[permissions]; if (methods !== null) { - return { policy: 'methods', methods }; + return methodsAccess(methods); } return { policy: 'full' }; @@ -189,34 +191,109 @@ export function envelopeToAccess( }; } if (envelope.methods !== null) { - return { access: { policy: 'methods', methods: envelope.methods.map(m => m.toUpperCase()) }, unresolved: [] }; + return { access: methodsAccess(envelope.methods.map(m => m.toUpperCase())), unresolved: [] }; } return { access: { policy: 'full' }, unresolved: [] }; } -const READ_WRITE = ['GET', 'PATCH', 'POST', 'PUT']; +const ACTION_LEVELS: ActionLevel[] = ['read', 'write', 'delete']; -/** The consent page's name for an access: Full access, Read & write, Read only, Custom, No access. */ +/** The level One reads a method as; HEAD and the like stand for none. */ +function levelOfMethod(method: string): ActionLevel | null { + switch (method.toUpperCase()) { + case 'GET': + return 'read'; + case 'POST': + case 'PUT': + case 'PATCH': + return 'write'; + case 'DELETE': + return 'delete'; + default: + return null; + } +} + +/** A method-scoped access, with the levels its methods stand for. */ +function methodsAccess(methods: string[]): ConnectionAccess { + const levels = new Set(methods.map(levelOfMethod)); + return { policy: 'methods', methods, access: ACTION_LEVELS.filter(l => levels.has(l)) }; +} + +/** The name for a set of levels; a set no name covers is custom. */ +function levelOfSet(levels: Set): AccessLevel { + const key = ACTION_LEVELS.filter(l => levels.has(l)).join(','); + switch (key) { + case '': + return 'none'; + case 'read': + return 'read-only'; + case 'write': + return 'write-only'; + case 'read,write': + return 'read-write'; + case 'read,write,delete': + return 'full'; + default: + return 'custom'; + } +} + +/** The consent page's name for an access, judged by level as One judges it. */ export function accessLevel(access: ConnectionAccess): AccessLevel { switch (access.policy) { case 'full': return 'full'; - case 'methods': { - const set = [...new Set(access.methods.map(m => m.toUpperCase()))].sort(); - if (set.length === 0) return 'none'; - if (set.length === 1 && set[0] === 'GET') return 'read-only'; - if (set.join(',') === READ_WRITE.join(',')) return 'read-write'; - return 'custom'; - } + case 'methods': + return levelOfSet(new Set(access.methods.map(levelOfMethod).filter((l): l is ActionLevel => l !== null))); case 'actions': return access.actions.length === 0 ? 'none' : 'custom'; } } +const VIEWER_LEVELS: Record = { + none: [], + read: ['read'], + write: ['write'], + read_write: ['read', 'write'], + full: ['read', 'write', 'delete'], + custom: null, +}; + +/** + * What a call through the connection may really do: the key's access held to + * the person's own level, as One holds it. An action list, or a custom share, + * names actions a level cannot, so either stays custom unless the other is none. + */ +export function heldLevel(access: ConnectionAccess, viewer: ViewerAccessLevel | undefined): AccessLevel { + const own = accessLevel(access); + if (!viewer || viewer === 'full' || own === 'none') return own; + const allowed = VIEWER_LEVELS[viewer]; + if (allowed?.length === 0) return 'none'; + if (allowed === null || access.policy === 'actions') return 'custom'; + const keyLevels = access.policy === 'full' ? ACTION_LEVELS : access.access; + return levelOfSet(new Set(keyLevels.filter(l => allowed.includes(l)))); +} + +const VIEWER_LABELS: Record = { + none: 'No access', + read: 'Read only', + write: 'Write only', + read_write: 'Read & write', + full: 'Full access', + custom: 'Custom', +}; + +/** The dashboard's name for a person's own level on a connection. */ +export function viewerLevelLabel(level: ViewerAccessLevel): string { + return VIEWER_LABELS[level]; +} + const LEVEL_LABELS: Record = { full: 'Full access', 'read-write': 'Read & write', 'read-only': 'Read only', + 'write-only': 'Write only', custom: 'Custom', none: 'No access', }; @@ -236,7 +313,7 @@ export function formatAccess(access: ConnectionAccess, maxActions = 2): string { case 'full': return LEVEL_LABELS.full; case 'methods': - return access.methods.join(', '); + return access.access.map(l => l[0].toUpperCase() + l.slice(1)).join(', '); case 'actions': { if (access.actions.length === 0) return 'none'; const shown = access.actions.slice(0, maxActions).map(a => `${a.title} (${a.method})`); diff --git a/src/lib/api-own-access.test.ts b/src/lib/api-own-access.test.ts index f3b77fa..eeaf0dd 100644 --- a/src/lib/api-own-access.test.ts +++ b/src/lib/api-own-access.test.ts @@ -47,3 +47,25 @@ describe('OneApi.getOwnAccess (GET /v1/access/me)', () => { await assert.rejects(new OneApi('k', 'https://api.test/v1').getOwnAccess(), ApiError); }); }); + +describe('OneApi.listViewerLevels (GET /v1/connections)', () => { + it('maps each connection key to the person\'s level across pages', async () => { + const pages = [ + { rows: [{ key: 'live::gmail::default::g', viewerAccessLevel: 'read' }], pages: 2 }, + { rows: [{ key: 'live::slack::default::s', viewerAccessLevel: 'full' }], pages: 2 }, + ]; + const urls: string[] = []; + globalThis.fetch = (async (url: string | URL | Request) => { + urls.push(String(url)); + return new Response(JSON.stringify(pages[urls.length - 1]), { status: 200 }); + }) as typeof fetch; + const levels = await new OneApi('k', 'https://api.test/v1').listViewerLevels(); + assert.deepEqual([...levels], [['live::gmail::default::g', 'read'], ['live::slack::default::s', 'full']]); + assert.deepEqual(urls, ['https://api.test/v1/connections?page=1&limit=100', 'https://api.test/v1/connections?page=2&limit=100']); + }); + + it('is empty from an older backend that sends no level', async () => { + answer(200, JSON.stringify({ rows: [{ key: 'live::gmail::default::g' }], pages: 1 })); + assert.equal((await new OneApi('k', 'https://api.test/v1').listViewerLevels()).size, 0); + }); +}); diff --git a/src/lib/api.ts b/src/lib/api.ts index abac08c..df0cb07 100644 --- a/src/lib/api.ts +++ b/src/lib/api.ts @@ -22,6 +22,7 @@ import type { FoundActions, KeyAccessDocument, AccessControlSettings, + ViewerAccessLevel, } from './types.js'; export class ApiError extends Error { @@ -196,6 +197,30 @@ export class OneApi { return allConnections; } + /** + * The person's own level on each connection key (`GET /v1/connections`, the + * route that carries `viewerAccessLevel`). Empty from an older backend that + * sends none. + */ + async listViewerLevels(): Promise> { + const levels = new Map(); + let page = 1; + let totalPages = 1; + + do { + const response = await this.request<{ rows?: { key: string; viewerAccessLevel?: ViewerAccessLevel }[]; pages?: number }>( + `/connections?page=${page}&limit=100` + ); + for (const row of response.rows || []) { + if (row.viewerAccessLevel) levels.set(row.key, row.viewerAccessLevel); + } + totalPages = response.pages || 1; + page++; + } while (page <= totalPages); + + return levels; + } + async deleteConnection(id: string): Promise { await this.requestFull({ path: `/vault/connections/${id}`, method: 'DELETE' }); } diff --git a/src/lib/guide-content.ts b/src/lib/guide-content.ts index 782c1fe..76069ff 100644 --- a/src/lib/guide-content.ts +++ b/src/lib/guide-content.ts @@ -142,7 +142,7 @@ Request specific sections: - Requires Node.js 22.23.4+, 24.22.1+ or 26.12.1+. Older Node trusts the compromised eMudhra CA certificates, so every command exits 1 there with \`"code": "NODE_UPGRADE_REQUIRED"\` and an \`upgrade\` field holding the command for the user's setup. Don't retry: show the user that command and ask them to update Node.js - Always read **knowledge** before executing any action - Connection keys come from \`one connection list\` — don't hardcode them -- \`connection list\` also reports an \`access\` field per connection (\`full\` / \`methods\` / \`actions\`, plus a \`level\`: full, read-write, read-only, custom, none) — what One enforces for this key, narrowed by \`one config\`. Read it before planning so you don't propose an action that will be refused. \`accessSource: "local"\` means One did not report it, so it is unverified +- \`connection list\` also reports an \`access\` field per connection (\`full\` / \`methods\` / \`actions\`, plus a \`level\`: full, read-write, read-only, write-only, custom, none) — what One enforces for this key, narrowed by \`one config\`. In an organization, \`viewerAccessLevel\` is the person's own level (their share or App Controls) and \`effectiveLevel\` what a call can really do under both. Read them before planning so you don't propose an action that will be refused. \`accessSource: "local"\` means One did not report it, so it is unverified - Skills stay in lockstep with the CLI version automatically — every command checks a \`.one-cli-version\` marker in the canonical skill dir and refreshes the files if the CLI has been upgraded. Check manually with \`one config skills status\`; force a resync with \`one config skills sync\` - Building an app whose users connect their own tools? \`one skills add connect\` (run inside the app) installs the One Connect skill from the \`@withone/connect\` version the app uses, into \`.agents/skills/one-connect\` and \`.claude/skills/one-connect\`. \`one --agent skills list\` shows what is installed; any \`one\` command in the project refreshes it after an SDK upgrade `; @@ -159,14 +159,16 @@ Always follow this sequence. Never execute without reading the action's document one --agent connection list \`\`\` -Returns platforms, status, connection keys, tags, and an \`access\` field per connection: what One enforces for this key (the consent page's choices, or the dashboard's), narrowed by \`one config\`. \`access.level\` names it as the consent page does (full, read-write, read-only, custom, none): +Returns platforms, status, connection keys, tags, and an \`access\` field per connection: what One enforces for this key (the consent page's choices, or the dashboard's), narrowed by \`one config\`. \`access.level\` names it as the consent page does (full, read-write, read-only, write-only, custom, none): | \`access\` | Meaning | |----------|---------| | \`{"policy": "full"}\` | Every action on the connection | -| \`{"policy": "methods", "methods": ["GET"]}\` | Only actions with these HTTP methods will execute | +| \`{"policy": "methods", "methods": ["GET"], "access": ["read"]}\` | Only actions at the levels in \`access\` will execute. One judges an action by what it does (\`read\`, \`write\`, \`delete\`), not its HTTP method, so a POST search runs under \`read\` | | \`{"policy": "actions", "actions": [{"actionId", "title", "method"}]}\` | Only these exact actions — use them directly: \`actions load \` reads their docs, no find needed | +In an organization, an admin may share an app with you at a lower level, or cap it with App Controls. Then the connection also carries \`viewerAccessLevel\` (\`none\`, \`read\`, \`write\`, \`read_write\`, \`full\`, \`custom\`): the most you may run through it. One holds every call to both it and \`access\`, and \`effectiveLevel\` names what that leaves, in \`access.level\`'s words. Plan by \`effectiveLevel\`. An older API sends neither. + \`accessSource\` is \`server\` when One reported it, \`local\` when it could not (then it is unverified). Also present when relevant: \`knowledgeOnly: true\` (execution disabled — read the docs and write code instead), \`unresolvedActionIds\` (allowlisted ids that could not be looked up), and \`accessHint\` (a one-line summary of the restriction). Read \`access\` before planning — it prevents proposing an action that will be refused. The key's access changes in the dashboard (API keys); this CLI's own limits with \`one config\`. diff --git a/src/lib/types.ts b/src/lib/types.ts index 037fb02..78c9042 100644 --- a/src/lib/types.ts +++ b/src/lib/types.ts @@ -75,14 +75,26 @@ export interface GrantedAction { * `one list` answers "what can I do here" without a search. Same shape as the * MCP server's `ConnectionAccess` (`policy` discriminant): * - `full`: every action on the connection. - * - `methods`: only actions whose HTTP method is in the set. + * - `methods`: only actions at the levels the methods stand for, in `access` + * (GET is `read`, POST/PUT/PATCH `write`, DELETE `delete`). One judges an + * action by its level, not its HTTP method, so a POST search runs under `read`. * - `actions`: only these specific actions. */ export type ConnectionAccess = | { policy: 'full' } - | { policy: 'methods'; methods: string[] } + | { policy: 'methods'; methods: string[]; access: ActionLevel[] } | { policy: 'actions'; actions: GrantedAction[] }; +/** What an action does, as One classifies it and judges a grant by. */ +export type ActionLevel = 'read' | 'write' | 'delete'; + +/** + * The most a person may run through a connection, as their share or their + * organization's App Controls hold them (`viewerAccessLevel` on + * `GET /v1/connections`). A call is held to both this and the key's access. + */ +export type ViewerAccessLevel = 'none' | 'read' | 'write' | 'read_write' | 'full' | 'custom'; + /** * One rule of the key's server-side access, as `GET /v1/access/me` answers it. * A missing `methods` falls back to the document's top-level `methods`; a @@ -106,7 +118,7 @@ export interface KeyAccessDocument { } /** The access level a person picks on the consent page, for display. */ -export type AccessLevel = 'full' | 'read-write' | 'read-only' | 'custom' | 'none'; +export type AccessLevel = 'full' | 'read-write' | 'read-only' | 'write-only' | 'custom' | 'none'; /** * An allowlisted action id resolved to its metadata, including the platform it