You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 8b16445
Browse filesBrowse the repository at this point in the historyBrowse files
feat(spec): declare the optional ISecurityService.describeEffectiveAccess and its EffectiveAccess answer types (#31256)
<!-- claude-projects-attribution: {"github_login":"os-project-manager"}
-->
_Requested by **Leehom** · [project
thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1XGML1ZArFc2ffDxPnNbY42U)_Fixes#31238
Clause-②: yes (widening)
Metadata-protocol: none
## 维护者速读
- **改了什么**:只在 spec 的安全服务契约(`security-service.ts`)里新增三个 TypeScript 类型
`EffectivePermissionSetOrigin` / `EffectivePermissionSet` /
`EffectiveAccess`,和一个可选成员
`ISecurityService.describeEffectiveAccess?(userId,
callerContext?)`:查看某个用户实际生效的权限集,以及每个权限集是怎么来的(默认绑定、所任职位、直接授予,或由解析器派生:配置的平台所有者、AI
席位)。另有契约测试里的类型钉、两份再生成的导出清单和一个 spec patch changeset。
- **为什么改**:用户页的「权限集」标签对靠默认绑定和职位拿到权限的人显示 0(#31215)。服务端席位按路线 A 定:先在 spec
里声明这个回答的形状,再由 #31215 做插件、REST 和客户端。这张卡只是前半段。
- **风险与回滚**:纯类型加法,成员是可选的,现有安全服务实现不改也照样满足契约;没有 schema、可编写键或运行时行为变化。回滚即
revert。名字沿用 `DelegableScope` / `describeDelegableScope` 的先例,您对命名仍有否决窗口。
- **先看**:`packages/spec/src/contracts/security-service.ts` 的
`EffectivePermissionSetOrigin` 与 `describeEffectiveAccess?`
的注释(门禁与「不存在的用户按无权管理拒绝」两句)。
- **两分钟验证**:`pnpm --filter @objectstack/spec exec vitest run
src/contracts/security-service.test.ts`,预期 29
个全部通过,其中两条是本卡新增的可选成员与三种形状的类型钉。
- **需要你做的**:无,席位落地(契约复审后)。
## What changes
`packages/spec/src/contracts/security-service.ts`, beside
`DelegableScope` / `PositionGrantSummary`, TS interfaces with no Zod (a
wire answer, not authorable metadata), text as drafted in #31215's dev
report (`pm-orders/server/31215-spec-addition.md`) and re-read on
`origin/main` `733efbd4`:
1. `EffectivePermissionSetOrigin`: `{ kind: 'default' } | { kind:
'position'; position: string } | { kind: 'direct' } | { kind: 'derived';
source: 'platform_admin_config' | 'ai_access' }` (the fourth kind added
in the fix round, see below). `default` is a binding to the `everyone`
audience anchor (deployment baseline, an app's `isDefault` set, an
accepted package default; ADR-0090 D5) or the human baseline the
resolution adds (`external_default` for an external member); `position`
is a held position's definition naming the set (ADR-0131 D3/D4), never
`everyone`; `direct` is a `sys_user_permission_set` row of the user's.
2. `EffectivePermissionSet`: `{ name: string; origins:
EffectivePermissionSetOrigin[] }`, at least one origin; a set reached
two ways is listed once with both.
3. `EffectiveAccess`: `{ userId: string; organizationId: string | null;
positions: string[]; permissionSets: EffectivePermissionSet[] }`, the
sets in the resolver's own order (defined in the docblock; see the fix
round), in the caller's active organization vetted for the described
user as `explain` vets it.
4. `ISecurityService.describeEffectiveAccess?(userId: string,
callerContext?: SecurityContext): Promise<EffectiveAccess>`, after
`describeDelegableScope`, docblock citing ADR-0090 D6/D12: resolved by
the resolver enforcement uses; gated as `explain` is (`manage_users`,
organization administration of an organization the user is a member of,
or a delegated `adminScope` covering the user, the three arms
`explainAccessForCaller` in `security-plugin-explain-access.ts` checks
today); an unknown user refused exactly as one the caller may not manage
(seat decision 6711854159; `explain` itself answers an admitted caller
404 for an unknown id, and #31215 names that difference); OPTIONAL,
callers feature-detect and answer "not served" (a REST door answers 501,
as the security doors in `packages/rest/src/security-routes.ts` do for
an absent member).
5. `packages/spec/api-surface/contracts.json` and
`packages/spec/export-origins/contracts.json`: regenerated by
`check:generated --fix` (the only two artifacts it proved stale); each
gains exactly the three new names.
6. `.changeset/31238-security-service-effective-access.md`:
`'@objectstack/spec': patch`. The order named `minor`; AGENTS.md
(Post-Task Checklist 3) and `check-changeset-no-major` grade a
`Metadata-protocol: none` change `patch` (maintainer ruling A on the
level axis), and with this body the gate refuses `minor` (reproduced
locally with a `pull_request` event), so the entry is `patch`.
No plugin-security, rest, client or core change: those are #31215's,
which is serial behind this card and does not close with it.
One wording addition to the drafted docblock: the absence paragraph says
callers feature-detect and answer "not served", never an empty list, in
the words of the `reopenAudienceBindingSuggestion?` precedent. The
order's name precedent reads `describeDelegableScope?`; on `main` that
member is required (`REQUIRED_MEMBERS` lists it), so the optional-member
pins follow the `reopenAudienceBindingSuggestion?` /
`checkControlledByParentWrite?` pins instead.
## Tests
`packages/spec/src/contracts/security-service.test.ts`, two new cases
beside the other optional-member pins:
- `describeEffectiveAccess is OPTIONAL`: a stub without it satisfies
`ISecurityService`; an unguarded call does not compile
(`@ts-expect-error`); listing it as a `RequiredMember` does not compile;
a stub with it resolves the answer. `REQUIRED_MEMBERS` does not move.
- `EffectiveAccess` shapes: the three origins, a `position` origin
without its name and an unknown `kind` refused (`@ts-expect-error`),
`toEqualTypeOf` on `EffectivePermissionSet`, `EffectiveAccess` and the
member's signature, and an exhaustive `switch` with a `never` arm.
Reverse check (one-off, not kept): with the member made required,
`check:test-typecheck` turns red on this file (4 type errors) and is
green again after `git checkout HEAD --
packages/spec/src/contracts/security-service.ts` (blob hash matched
HEAD).
## Verification
Local gates on the final head `80410d2f`: 82 derived by `dispatch-gates
--commands`, 81 exit 0, 1 NOT MEASURED (`check:dual-build-cjs-loads`,
exit 3: it needs every package's `dist`, CI's). `--ran` reconciles 82
accounted, 0 unrun. `pnpm --filter @objectstack/spec test`: 821 files /
25966 tests passed (1 todo); `pnpm --filter @objectstack/spec run
typecheck` exit 0 (test layer included); `check:generated` green after
`--fix`; `check-changeset-no-major` with a `pull_request` event carrying
this body exit 0. Details in the card's `os-dev-report`; CI runs the
full set.
## Fix round (contract review 6712477832, FAIL → this head)
- **M1:** the three kinds could not express sets the resolver confers
with no grant row and no position. The union gains `{ kind: 'derived';
source: 'platform_admin_config' | 'ai_access' }`, one docblock per
source (`OS_PLATFORM_OWNER_EMAIL` → `admin_full_access` and
platform-admin standing; `sys_user.ai_access` → `ai_seat`), measured
over every channel of `resolveUserAuthzGrants` and the plugin's
human-baseline join. API-key scopes, an agent's ceiling and the guest
anchor are named as not origins (not the user's own resolution). The
exhaustive switch covers four kinds and both sources.
- **S1:** the gate sentence says an unknown id is refused exactly as an
unmanageable one, for every caller, unlike `explain`'s 404 to an
admitted caller.
- **S2:** `external_default` reports both `{ kind: 'position', position:
'org_external' }` and `{ kind: 'default' }`; `positions` lists the
derived `platform_admin` first and `everyone` last, neither ever an
origin.
- **S3:** the order is the resolver's: grant rows in grant order,
position-bound sets in held-position order, derived
(`admin_full_access`, then `ai_seat`), then the human baseline; a set
already listed keeps its place and gains the later origin.
- **Type Check red on `80410d2f`:** plugin-security's
`registered-security-service-members.pin.test.ts` lists
`describeEffectiveAccess` as `optional` (claim amendment 6712494974
added that one file).
- Changeset text refreshed for the derived kind and the order; level
unchanged (`patch`).
---
_Generated by [Claude
Code](https://claude.ai/code/session_01FEkQ5odNVgHTd2MQbQCp5t)_
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01FEkQ5odNVgHTd2MQbQCp5t
<!-- signed: domain:spec#1 · os-project-manager ·
session_01FEkQ5mw7HFYn9o4LEGMQdK -->
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: objectstack-fleet[bot] <332303061+objectstack-fleet[bot]@users.noreply.github.com>
feat(spec): declare the optional `ISecurityService.describeEffectiveAccess` and its `EffectiveAccess` answer types
6
+
7
+
Clause-②: yes (widening)
8
+
Metadata-protocol: none
9
+
10
+
`@objectstack/spec/contracts` gains three exported types and one optional member of the `security` service contract, beside `DelegableScope` / `describeDelegableScope`:
11
+
12
+
-`EffectivePermissionSetOrigin`: how a permission set reaches a user, one of `{ kind: 'direct' }` (a `sys_user_permission_set` grant row of the user's), `{ kind: 'position'; position }` (a held position's definition names the set, including a built-in identity position's static binding), `{ kind: 'default' }` (a binding to the `everyone` audience anchor, or the human baseline the resolution adds) and `{ kind: 'derived'; source }` (standing the resolver confers without a grant row or a position, from the closed sources `'platform_admin_config'` and `'ai_access'`).
13
+
-`EffectivePermissionSet`: `{ name, origins }`, at least one origin; a set reached two ways is listed once with both.
14
+
-`EffectiveAccess`: `{ userId, organizationId, positions, permissionSets }`, in the caller's organization; `positions` and `permissionSets` in the resolver's own order, which the contract spells out.
15
+
-`ISecurityService.describeEffectiveAccess?(userId, callerContext?)`: describe a user's effective permission sets and where each comes from, resolved by the resolver enforcement uses, gated as `explain` is (`manage_users`, organization administration of an organization the user belongs to, or a delegated `adminScope` covering the user), with an unknown user refused exactly as one the caller may not manage. Optional: a security service that predates it omits it, and callers feature-detect and answer that the read is not served.
16
+
17
+
A TypeScript contract only: no schema, authorable key or runtime answer changes here. The reference implementation and its REST door land separately.
0 commit comments