Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <actionId>` reads their docs, no find needed.
Expand All @@ -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.
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@withone/cli",
"version": "2.14.15",
"version": "2.15.0",
"description": "CLI for managing One",
"type": "module",
"files": [
Expand Down
6 changes: 4 additions & 2 deletions skills/one/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <actionId>` 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.
Expand Down
41 changes: 31 additions & 10 deletions src/commands/connection.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<void> {
if (output.isAgentMode()) {
Expand Down Expand Up @@ -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<string, ViewerAccessLevel>()),
]);

// The CLI's own access settings (`one config`) narrow it further.
Expand Down Expand Up @@ -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] }),
Expand Down Expand Up @@ -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(
[
Expand All @@ -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) {
Expand Down
58 changes: 50 additions & 8 deletions src/lib/access.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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[] = [
Expand All @@ -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'] }
);
});

Expand All @@ -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(
Expand All @@ -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', () => {
Expand Down
Loading
Loading