Skip to content

Commit f6c6193

Browse files
feat(plugin-security): one business sentence per built-in permission set, translated (#26090)
<!-- claude-projects-attribution: {"github_login":"os-project-manager"} --> _Requested by **Leehom** · [project thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1X1tNqzSWRgqddaNpX6CJvVQ)_ Fixes #25967 Clause-②: no Metadata-protocol: none ## What changes Setup → Permission Sets lists the platform's own permission sets next to every app's. Five of them showed no description. The no-bypass organization admin set and the three MCP agent sets showed text written for platform engineers. So an administrator choosing a set could not tell an administrator set from a member set. Each of the nine sets in `defaultPermissionSets` now has one plain sentence (at most 160 characters, in the voice of objectstack-ai/hotcrm#2303) saying who holds it and what it opens or withholds. The engineering detail from the old no-bypass and MCP descriptions now lives in code comments beside each set. The ADR-0105 D4 / finding F2 note stays in the comment, so the string names no decision id. | Set | Description (en) | | --- | --- | | `admin_full_access` | Platform operators: read and change every record in every organization, manage all users and settings, and author apps in Studio. | | `organization_admin` | Owners and admins of an organization: full control of its records and members in Setup, but no app authoring or platform-wide settings. | | `organization_admin_no_bypass` | Organization admins on a deployment with no wall between organizations: the same administration, but only the records their ownership and sharing open. | | `member_default` | Every signed-in member's baseline: their own profile, keys and inbox and the member directory; business records come from their other sets. | | `viewer_readonly` | Read-only users: read records across every object, as far as sharing allows, but create, edit or delete nothing. | | `external_default` | People from outside the organization, such as customers or suppliers: their own profile and records, plus only what is shared with them. | | `mcp_agent_data_read` | AI assistants a user connects with read access: they read what that user can read and change nothing. | | `mcp_agent_data_write` | AI assistants a user connects with read and write access: they read and change what that user can, except user and sign-in data. | | `mcp_agent_restricted` | AI assistants a user connects without data access: they can run the actions they were allowed, but read or change no record. | **Translations.** zh-CN, ja-JP and es-ES (the three locales this plugin's bundle already carries) get each sentence through the `permissions.NAME.description` group that #25652 added. `translatePermissionSet` overlays it on `GET /meta/permission`. The entries are hand-authored in `packages/plugins/plugin-security/src/translations/permission-sets.ts` and merged into `SecurityTranslations`. The generated `*.objects.generated.ts` files are not touched. No set's grants, name or label changed. **Files:** `default-permission-sets.ts` (descriptions and comments), `translations/permission-sets.ts` (new), `translations/index.ts` (merge), `objects/permission-set-descriptions.test.ts` (new pin), `objects/default-permission-sets.test.ts` (the admin capability pin now leaves the copy out of its comparison), one `patch` changeset. ## Evidence Live read, `pnpm dev:crm -- --fresh` built from head `a42ae5be`, signed in as the seeded admin. This is `GET /api/v1/meta/permission?scope=environment`, the list behind `/apps/setup/metadata/permission`. With `Accept-Language: zh-CN` it serves, for example: - `organization_admin`: 组织的所有者和管理员:在设置中全面管理本组织的记录和成员,但不能构建应用或修改平台级设置。 - `viewer_readonly`: 只读用户:在共享允许的范围内查看所有对象的记录,但不能新建、编辑或删除任何内容。 All nine built-in sets served their zh-CN sentence and, under `en`, their English sentence. The CRM example declares only `en` and `zh-CN` (`GET /api/v1/i18n/locales`), so ja-JP was read on `pnpm dev:todo -- --fresh` (it declares ja-JP), and all nine ja-JP sentences were served. No example declares es-ES, so es-ES is pinned at unit level only. I did not build the console in this container, so there is no browser screenshot. The REST read above is the list the page renders. ## Tests (head `a42ae5be`) - `pnpm --filter @objectstack/plugin-security test`: Test Files 224 passed (224), Tests 4741 passed, 45 skipped. `pnpm --filter @objectstack/plugin-security typecheck`: exit 0. - New pin `permission-set-descriptions.test.ts`: every set carries one sentence (no line break, at most 160 characters, one closing full stop, no code span, no set id), no two sets share a description, and each translated locale carries exactly the nine sets with a translated sentence and no label. - Ablation, run on the committed tree (`scripts/ablation-replace.mjs`, then restored, blob hashes equal to HEAD): - renaming `viewer_readonly` in all three locale groups failed 6 tests; - deleting `viewer_readonly`'s source description failed 1 test. - `default-permission-sets.test.ts` "parsed declaration deep-equals the pre-#11965 inline literal" went red when the admin set gained a description. It now compares the set without its `description`, which is copy, not capability. The capability literal is unchanged. ## Gates `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 69 families on `a42ae5be`. All 69 ran and every exit is 0. `--ran` reconciliation: 69 derived, 69 run, 0 NOT-MEASURED, 0 UNRUN. `check-plugin-teardown-shape --self-test` first exited 3 because the checkout is shallow. It exited 0 after fetching its positive-control commit. `pnpm check:i18n` reported all bundles in sync. Scoped `eslint --no-inline-config packages/plugins/plugin-security` exited 0. CI runs everything else. ## Acceptance notes - **Why the translations are hand-authored, not generated.** This plugin's extract runs objects-only, and stack mode needs a flag spelling that the `check:i18n` docstring harvester (`scripts/i18n-bundle-surface.mjs`) does not recognise. Generating the group would have meant changing that tooling and renaming the four generated exports. I kept to the claim's file surface and did neither. The cost is that no provenance table judges these entries. If a source sentence changes later, its three translations go stale silently unless the same change re-translates them. The file header says so. The new pin catches a missing or English-copy entry, not a stale one. - **Labels stay untranslated.** Labels were out of scope under the ruling. The zh-CN read above serves `Administrator — Full Access` next to the app's own `CRM 销售用户`. This is reported to the seat, not fixed here. - Main moved 12 commits after the branch point. None touch `plugin-security` or the translation code, and `git merge-tree` merges cleanly. I did not merge main. - No other open PR touches `default-permission-sets.ts` or `plugin-security/src/translations/` (all 40 open PRs read at pr_create). --- _Generated by [Claude Code](https://claude.ai/code/session_01JzRY5bknrRuK7CHuyu6Aw7)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent cc378e9 commit f6c6193

6 files changed

Lines changed: 290 additions & 16 deletions

File tree

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@objectstack/plugin-security': patch
3+
---
4+
5+
Every built-in permission set says who holds it, in English, Chinese, Japanese and Spanish
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
Setup → Permission Sets lists the platform's own permission sets beside every app's. Five of them (*Administrator — Full Access*, *Organization Administrator*, *Member — Standard Access*, *Viewer — Read-Only* and *External Member — Own Records*) had no description, and the no-bypass organization administrator set and the three MCP agent sets had descriptions written for platform engineers. An administrator picking a set for a new user could not tell an administrator set from a member set.
11+
12+
Each built-in set now has one plain sentence saying who holds it and what it opens or withholds. For example, *Organization Administrator* reads "Owners and admins of an organization: full control of its records and members in Setup, but no app authoring or platform-wide settings." The sentences are translated into zh-CN, ja-JP and es-ES through the permission-set group of the translation bundle (`permissions.<name>.description`), so the page shows them in the user's language. The engineering detail that used to be in the no-bypass and MCP descriptions is now in code comments.
13+
14+
No set's grants, name or label changed. This changes only the text shown about each set, not its permissions.

‎packages/plugins/plugin-security/src/objects/default-permission-sets.test.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -394,6 +394,10 @@ describe('sys_comment_reaction delete is ownership-shaped (#22566)', () => {
394394
* And `manage_mailboxes` (ruling 6116489638, Q4 → A on the inbound-mail record —
395395
* platform and organization administrators hold the mailbox administrator
396396
* capability by default).
397+
*
398+
* The set's `description` is admin-facing copy, not capability, so it is left
399+
* out of the comparison (its shape is pinned by
400+
* `permission-set-descriptions.test.ts`).
397401
*/
398402
describe('admin_full_access imports the kernel capability declaration unchanged (#11965)', () => {
399403
it('parsed declaration deep-equals the pre-#11965 inline literal', () => {
@@ -432,7 +436,8 @@ describe('admin_full_access imports the kernel capability declaration unchanged
432436
.map(([name]) => [`sys_user.${name}`, { readable: true, editable: true }]),
433437
),
434438
});
435-
expect(setByName('admin_full_access')).toEqual(preMove);
439+
const { description: _copy, ...declared } = setByName('admin_full_access') as Record<string, unknown>;
440+
expect(declared).toEqual(preMove);
436441
});
437442

438443
it('[#21260] no other shipped set carries the ledger audit capability: every other position holds it only by explicit grant', () => {

‎packages/plugins/plugin-security/src/objects/default-permission-sets.ts‎

Lines changed: 39 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -324,6 +324,11 @@ const baseDefaultPermissionSets: PermissionSet[] = [
324324
PermissionSetSchema.parse({
325325
name: ADMIN_FULL_ACCESS,
326326
label: 'Administrator — Full Access',
327+
// Admin-facing copy on Setup → Permission Sets: one business sentence, no
328+
// engineering terms (the detail lives in the comments beside each set).
329+
// `permission-set-descriptions.test.ts` pins the shape for every set here.
330+
description:
331+
'Platform operators: read and change every record in every organization, manage all users and settings, and author apps in Studio.',
327332
// [#11965 / #11663 Choice 6A] The capability CONTENT (object wildcard +
328333
// `systemPermissions`) is the kernel platform-admin declaration exported
329334
// by `@objectstack/spec` — one list, imported here and read by core's
@@ -378,6 +383,10 @@ const baseDefaultPermissionSets: PermissionSet[] = [
378383
PermissionSetSchema.parse({
379384
name: ORGANIZATION_ADMIN,
380385
label: 'Organization Administrator',
386+
// Inherited by `organization_admin_no_bypass` through the derivation's
387+
// spread, which then writes its own.
388+
description:
389+
'Owners and admins of an organization: full control of its records and members in Setup, but no app authoring or platform-wide settings.',
381390
objects: {
382391
'*': {
383392
allowRead: true,
@@ -590,6 +599,10 @@ const baseDefaultPermissionSets: PermissionSet[] = [
590599
PermissionSetSchema.parse({
591600
name: 'member_default',
592601
label: 'Member — Standard Access',
602+
// No business object is named here (see the NO-WILDCARD note below), so the
603+
// copy says where business access comes from instead.
604+
description:
605+
"Every signed-in member's baseline: their own profile, keys and inbox and the member directory; business records come from their other sets.",
593606
objects: {
594607
// [#5491] NO `'*'` WILDCARD GRANT. This set is the additive `everyone`
595608
// baseline — it resolves for EVERY authenticated member — and object
@@ -1130,6 +1143,10 @@ const baseDefaultPermissionSets: PermissionSet[] = [
11301143
PermissionSetSchema.parse({
11311144
name: 'viewer_readonly',
11321145
label: 'Viewer — Read-Only',
1146+
// A read wildcard without the superuser bits: row visibility is still
1147+
// sharing's, so the copy says "as far as sharing allows", not "every record".
1148+
description:
1149+
'Read-only users: read records across every object, as far as sharing allows, but create, edit or delete nothing.',
11331150
objects: {
11341151
'*': {
11351152
allowRead: true,
@@ -1282,6 +1299,8 @@ const baseDefaultPermissionSets: PermissionSet[] = [
12821299
PermissionSetSchema.parse({
12831300
name: EXTERNAL_DEFAULT_PERMISSION_SET,
12841301
label: 'External Member — Own Records',
1302+
description:
1303+
'People from outside the organization, such as customers or suppliers: their own profile and records, plus only what is shared with them.',
12851304
objects: {
12861305
// Self-service profile edits, bounded exactly as `member_default`'s
12871306
// (`sys_user_self` below + the ADR-0092 D2 column whitelist).
@@ -1475,20 +1494,24 @@ const baseDefaultPermissionSets: PermissionSet[] = [
14751494
PermissionSetSchema.parse({
14761495
name: MCP_AGENT_PERMISSION_SET_READ,
14771496
label: 'MCP Agent — Read Only',
1497+
// The read-only ceiling for an agent acting on behalf of a user, from the
1498+
// OAuth `data:read` scope; bounded by the delegating user's own
1499+
// permissions (the D10 intersection above).
14781500
description:
1479-
'Read-only ceiling for an AI agent acting on behalf of a user (OAuth `data:read`). ' +
1480-
'Bounded by the delegating user\'s own permissions.',
1501+
'AI assistants a user connects with read access: they read what that user can read and change nothing.',
14811502
objects: {
14821503
'*': { allowRead: true },
14831504
},
14841505
}),
14851506
PermissionSetSchema.parse({
14861507
name: MCP_AGENT_PERMISSION_SET_WRITE,
14871508
label: 'MCP Agent — Read & Write',
1509+
// The read+write ceiling for an agent acting on behalf of a user, from the
1510+
// OAuth `data:write` scope: full CRUD, still bounded by the delegating
1511+
// user's own permissions. The better-auth managed identity tables stay
1512+
// read-only ("user and sign-in data" in the copy).
14881513
description:
1489-
'Read+write ceiling for an AI agent acting on behalf of a user (OAuth `data:write`). ' +
1490-
'Full CRUD, still bounded by the delegating user\'s own permissions. ' +
1491-
'Identity tables stay read-only (better-auth managed).',
1514+
'AI assistants a user connects with read and write access: they read and change what that user can, except user and sign-in data.',
14921515
objects: {
14931516
'*': { allowRead: true, allowCreate: true, allowEdit: true, allowDelete: true },
14941517
// Even a write-scoped agent must not mutate better-auth identity tables
@@ -1500,9 +1523,11 @@ const baseDefaultPermissionSets: PermissionSet[] = [
15001523
PermissionSetSchema.parse({
15011524
name: MCP_AGENT_PERMISSION_SET_RESTRICTED,
15021525
label: 'MCP Agent — No Data Access',
1526+
// The no-object-access floor for an agent with no data scope (for example
1527+
// `actions:execute` only). It keeps the resolved set list non-empty so
1528+
// enforcement fails CLOSED, never open.
15031529
description:
1504-
'No-object-access floor for an agent with no data scope (e.g. `actions:execute` only). ' +
1505-
'Keeps the resolved set list non-empty so enforcement fails CLOSED, never open.',
1530+
'AI assistants a user connects without data access: they can run the actions they were allowed, but read or change no record.',
15061531
objects: {},
15071532
}),
15081533
];
@@ -1534,6 +1559,12 @@ const baseDefaultPermissionSets: PermissionSet[] = [
15341559
function deriveWallLessOrgAdmin(base: PermissionSet): PermissionSet {
15351560
// [ADR-0105 D4 / finding F2] The description is admin copy on Setup's
15361561
// Permission Sets page, so the decision ids stay here, not in the string.
1562+
// The engineering reading: organization administration WITHOUT blanket
1563+
// record visibility, granted instead of `organization_admin` when the tenancy
1564+
// posture enforces no organization wall, where nothing would bound the
1565+
// superuser bits. Ownership, sharing and business RLS still apply; grant
1566+
// `admin_full_access` (or an explicit set carrying the bits) when a
1567+
// deployment-wide data superuser is genuinely intended.
15371568
const objects: Record<string, any> = { ...(base.objects ?? {}) };
15381569
const { viewAllRecords: _v, modifyAllRecords: _m, ...wildcardWithoutBypass } =
15391570
(objects['*'] ?? {}) as Record<string, unknown>;
@@ -1543,11 +1574,7 @@ function deriveWallLessOrgAdmin(base: PermissionSet): PermissionSet {
15431574
name: ORGANIZATION_ADMIN_NO_BYPASS,
15441575
label: 'Organization Administrator (no record bypass)',
15451576
description:
1546-
'Organization administration WITHOUT blanket record visibility. Granted instead of ' +
1547-
'`organization_admin` when the tenancy posture enforces no organization wall, where nothing ' +
1548-
'would bound the superuser bits. Ownership, sharing and business ' +
1549-
'RLS still apply; grant `admin_full_access` (or an explicit set carrying the bits) when a ' +
1550-
'deployment-wide data superuser is genuinely intended.',
1577+
'Organization admins on a deployment with no wall between organizations: the same administration, but only the records their ownership and sharing open.',
15511578
objects,
15521579
});
15531580
}
Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
import { describe, it, expect } from 'vitest';
4+
import { PermissionSetSchema } from '@objectstack/spec/security';
5+
import { defaultPermissionSets } from './default-permission-sets.js';
6+
import { SecurityTranslations } from '../translations/index.js';
7+
8+
/**
9+
* Every built-in permission set says who holds it.
10+
*
11+
* Setup → Permission Sets lists the platform's own sets beside every app's,
12+
* with each set's `description`. Five of them showed none and the no-bypass
13+
* and MCP agent sets showed text written for platform engineers, so an
14+
* administrator picking a set could not tell an administrator set from a
15+
* member set. This pins the business fact that every set in
16+
* `defaultPermissionSets` carries ONE plain sentence of at most 160
17+
* characters, and that every translated locale of this plugin's bundle
18+
* carries that sentence for it. It is deliberately not a copy of the wording,
19+
* which `default-permission-sets.ts` and `../translations/permission-sets.ts`
20+
* own.
21+
*
22+
* A sentence: non-empty, no line break, at most 160 characters, ends with one
23+
* full stop (`.`, or `。` in Chinese and Japanese) and holds no other sentence
24+
* break. Engineering terms stay in the code comments beside each set, so the
25+
* copy names no permission-set id and no code span.
26+
*/
27+
type AnyRec = Record<string, any>;
28+
29+
const MAX_LENGTH = 160;
30+
const TRANSLATED_LOCALES = Object.keys(SecurityTranslations).filter((l) => l !== 'en');
31+
const SET_NAMES = defaultPermissionSets.map((ps) => ps.name);
32+
33+
function expectOneSentence(text: unknown, where: string): void {
34+
expect(typeof text, `${where}: description missing`).toBe('string');
35+
const value = String(text);
36+
expect(value, `${where}: padded`).toBe(value.trim());
37+
expect(value.length, `${where}: empty`).toBeGreaterThan(0);
38+
expect([...value].length, `${where}: over ${MAX_LENGTH} characters`).toBeLessThanOrEqual(MAX_LENGTH);
39+
expect(value, `${where}: line break`).not.toMatch(/[\r\n]/);
40+
expect(value, `${where}: does not end with a full stop`).toMatch(/[.。]$/);
41+
// The only sentence break is the last character.
42+
expect(value.slice(0, -1), `${where}: more than one sentence`).not.toMatch(/[.!?](\s|$)|[。!?]/);
43+
// No engineer-facing spellings: code spans or a set's machine name.
44+
expect(value, `${where}: code span`).not.toMatch(/`/);
45+
for (const name of SET_NAMES) expect(value, `${where}: names ${name}`).not.toContain(name);
46+
}
47+
48+
describe('built-in permission set descriptions', () => {
49+
it('ships the nine built-in sets', () => {
50+
expect(SET_NAMES).toEqual([
51+
'admin_full_access',
52+
'organization_admin',
53+
'organization_admin_no_bypass',
54+
'member_default',
55+
'viewer_readonly',
56+
'external_default',
57+
'mcp_agent_data_read',
58+
'mcp_agent_data_write',
59+
'mcp_agent_restricted',
60+
]);
61+
});
62+
63+
it.each(defaultPermissionSets.map((ps) => [ps.name, ps] as const))(
64+
'%s has a one-sentence business description',
65+
(name, set) => {
66+
expectOneSentence(set.description, name);
67+
// The schema keeps the key (a stripped key would read back undefined).
68+
expect(PermissionSetSchema.parse(set).description).toBe(set.description);
69+
},
70+
);
71+
72+
it('gives no two sets the same description', () => {
73+
const texts = defaultPermissionSets.map((ps) => ps.description);
74+
expect(new Set(texts).size).toBe(texts.length);
75+
});
76+
77+
it('the bundle carries translated locales', () => {
78+
expect(TRANSLATED_LOCALES).toEqual(expect.arrayContaining(['zh-CN', 'ja-JP', 'es-ES']));
79+
});
80+
81+
describe.each(TRANSLATED_LOCALES)('%s', (locale) => {
82+
const group = ((SecurityTranslations[locale] as AnyRec | undefined)?.permissions ?? {}) as AnyRec;
83+
84+
it('translates exactly the built-in sets', () => {
85+
expect(Object.keys(group).sort()).toEqual([...SET_NAMES].sort());
86+
});
87+
88+
it.each(defaultPermissionSets.map((ps) => [ps.name, ps] as const))(
89+
'%s carries a translated one-sentence description',
90+
(name, set) => {
91+
const entry = group[name] as AnyRec | undefined;
92+
expectOneSentence(entry?.description, `${locale} ${name}`);
93+
expect(entry?.description, `${locale} ${name}: an English copy, not a translation`).not.toBe(set.description);
94+
// Descriptions only: the labels are not translated here.
95+
expect(entry && 'label' in entry, `${locale} ${name}: carries a label`).toBe(false);
96+
},
97+
);
98+
});
99+
});

‎packages/plugins/plugin-security/src/translations/index.ts‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ import { esESObjects } from './es-ES.objects.generated.js';
1818
import { zhCNGeneratedSourceHashes } from './zh-CN.source-hashes.generated.js';
1919
import { jaJPGeneratedSourceHashes } from './ja-JP.source-hashes.generated.js';
2020
import { esESGeneratedSourceHashes } from './es-ES.source-hashes.generated.js';
21+
import { zhCNPermissionSets, jaJPPermissionSets, esESPermissionSets } from './permission-sets.js';
2122

2223
/**
2324
* ## The provenance companions are READ here, not merely recorded
@@ -48,9 +49,24 @@ import { esESGeneratedSourceHashes } from './es-ES.source-hashes.generated.js';
4849
*/
4950
const enSource: TranslationData = { objects: enObjects };
5051

52+
/**
53+
* The built-in permission sets' description translations (`permissions`) are
54+
* hand-authored beside the generated objects (`permission-sets.ts` says why).
55+
* They sit outside `withSourceFallback`'s inputs: `enSource` carries no
56+
* `permissions` group, so no leaf of theirs is judged stale.
57+
*/
5158
export const SecurityTranslations: TranslationBundle = {
5259
en: enSource,
53-
'zh-CN': withSourceFallback({ objects: zhCNObjects }, enSource, undefined, zhCNGeneratedSourceHashes),
54-
'ja-JP': withSourceFallback({ objects: jaJPObjects }, enSource, undefined, jaJPGeneratedSourceHashes),
55-
'es-ES': withSourceFallback({ objects: esESObjects }, enSource, undefined, esESGeneratedSourceHashes),
60+
'zh-CN': {
61+
...withSourceFallback({ objects: zhCNObjects }, enSource, undefined, zhCNGeneratedSourceHashes),
62+
permissions: zhCNPermissionSets,
63+
},
64+
'ja-JP': {
65+
...withSourceFallback({ objects: jaJPObjects }, enSource, undefined, jaJPGeneratedSourceHashes),
66+
permissions: jaJPPermissionSets,
67+
},
68+
'es-ES': {
69+
...withSourceFallback({ objects: esESObjects }, enSource, undefined, esESGeneratedSourceHashes),
70+
permissions: esESPermissionSets,
71+
},
5672
};

0 commit comments

Comments
 (0)