Repository navigation
Commit 83a26c3
feat(plugin-auth): signed-out invitation preview read, an ADR-0138 D2 class-2-shaped door (#26151)
<!-- claude-projects-attribution: {"github_login":"os-project-manager"}
-->
_Requested by **Leehom** · [project
thread](https://claude.ai/code/project/chan_01TenzsRopZj4jMbvjX8uz1X?thread=cmsg_01TenzsRopZj4jMbvjX8uz1XG1RRdA5L2gYYiLonDFK6Un)_
Fixes #26020
Clause-②: no
Metadata-protocol: none
Ruling-ref: `6413975861` (Q1 → A, Q2 → B), maintainer 「26020 Q1 A Q2 B
26001 A」. Claim `6415981287`.
**Tier H.** The diff touches `docs/adr/0138-*` (a dated note under D2),
so this PR stays draft for the maintainer's merge.
## What it does
A person who opens an invitation link while signed out lands on a
sign-in page that cannot say who invited them or to what: better-auth's
`GET /organization/get-invitation` answers 401 without a session. This
adds the one read that page needs, exactly as the ruling scoped it.
**Route (for the `domain:ui` seat that reads it under the parent
card):**
```
GET /api/v1/auth/organization/invitation-preview?id=INVITATION_ID
```
| Case | Status | Body |
|:--|:--|:--|
| `pending`, not expired | 200 | `{ "success": true, "data": {
"organizationName": "Acme Corp", "inviterName": "Alice Owner", "email":
"b***@acme.test" } }` |
| unknown, expired, accepted, rejected or cancelled id; or its
organization is gone | 404 | `{ "success": false, "error": { "code":
"RESOURCE_NOT_FOUND", "message": "Invitation not found. It may have
expired, been used, or been withdrawn." } }`, the same bytes for every
case |
| more than 10 requests per client address per 60 s | 429 |
`RATE_LIMIT_EXCEEDED`, with `Retry-After` |
| a parameter other than `id`, a repeated `id`, or no `id` | 400 |
`VALIDATION_ERROR`, located |
- `email` is masked: first character of the local part, a fixed `***`,
then the domain. The fixed run does not reveal the local part's length;
a value with no usable `@` reads `***`.
- `inviterName` is `null` when the inviter's account no longer exists or
carries no name.
- The handler never reads the session, so a signed-in caller (inviter or
invitee) gets the identical body.
- Each of the five refused states is decided after the same single read,
so neither the body nor the read count tells them apart.
- The rate-limit window counts before anything is parsed or read, in the
kernel `cache` service when one is registered (the same lazy resolution
the auth rate-limit counters use, ADR-0069 D2), per process otherwise
with a one-time warning naming this budget.
## Files
- `packages/plugins/plugin-auth/src/invitation-preview.ts`: the handler
body, `maskInvitedEmail`, the closed query set, the rate-limit
constants.
- `packages/plugins/plugin-auth/src/auth-plugin.ts`: the raw-app mount
ahead of the catch-all, and the lazy counter store wired in `init()`.
- `packages/plugins/plugin-auth/src/auth-route-ledger.ts`: the row,
`source: 'objectstack'`, `disposition: 'public'` (the first row to use
that word), `requires: 'organization'`; the conformance pin of the
objectstack-mounted set gains it.
- `packages/rest/src/index.ts`: exports
`unknownQueryParamRefusalMessage`, the pure half of the AGENTS.md route
rule 5 recognition rule, so this door answers it with the one
implementation (the claim's amendment).
- `packages/qa/dogfood/test/anonymous-door-sweep.classification.ts`: the
route joins class 2's match. Without it the control-plane allowlist
would claim it (every `/api/v1/auth/*` route is allowlisted) and the
sweep would judge nothing. ADR-0138 criterion 2: the classification
follows the amendment (the claim's amendment).
- `docs/adr/0138-…md`: a dated note under D2's table admitting the route
as a class-2-shaped door, and a one-line amendment entry in the status
block.
- `.changeset/26020-signed-out-invitation-preview.md`:
`@objectstack/plugin-auth` patch, `@objectstack/rest` patch.
## Ruling ② premises, measured at `origin/main` `cc378e93ba`
- (a) **Holds.** `auth-route-ledger.ts` has `GET
/api/v1/auth/organization/get-invitation` only in
`BETTER_AUTH_MOUNTED_SURFACE` (the vendor's authenticated read) and no
anonymous invitation read.
- (b) **Holds.** None of D2's six classes admits this read; class 2 is
the share-link routes in `plugin-sharing`. One measured correction to
the ruling's re-check note: the auth domain does not call
`shouldDenyAnonymous` (`packages/runtime/src/domains/auth.ts` names it
only in a comment). The whole `/auth` namespace is exempt through
`isAuthGateAllowlisted`, so a new raw-app mount there is reachable
signed-out by construction. That is why the sweep classification edit is
needed. It does not change the ruling's route.
- (c) **Holds.** better-auth 1.7.12
`dist/plugins/organization/routes/crud-invites.mjs`, `getInvitation`:
the handler's first statement throws `UNAUTHORIZED` when
`getSessionFromCtx` finds no session, with no option guarding it. With a
session it returns the whole row plus `inviterEmail`, to the invitee
only. Pinned in the new suite (the PREMISE leg: 401).
## Tests
- `packages/plugins/plugin-auth/src/invitation-preview.test.ts` (new)
drives the real mount chain: `AuthPlugin.registerAuthRoutes` on a real
Hono app in front of a real `AuthManager` on the installed better-auth.
Invitations are issued, accepted, rejected and cancelled through the
vendor's own routes. Pins:
- the projection, by `toEqual` on the whole body;
- inviter and invitee signed in get a body `toEqual` the anonymous one;
- unknown, expired (by date and by status), accepted, rejected and
cancelled ids each answer 404 with the identical text, beside a live
control on the same staging that answers 200;
- org gone gives 404; inviter gone gives `inviterName: null`;
- the limit trips at the 11th request from one address, malformed probes
counting; another address keeps its own window; `Retry-After` falls
within the window;
- the closed query set;
- `maskInvitedEmail` cases.
- Ablations, each through `scripts/ablation-replace.mjs` (anchor hit 1 →
0, restored to the HEAD blob, `git diff HEAD` empty):
- deleting the `status !== 'pending'` line reds the uniform not-found
leg;
- unmasking the address reds the projection and inviter-gone legs;
- disabling the limit reds both rate-limit legs.
- Before the merge of `origin/main`: `pnpm --filter
@objectstack/plugin-auth test`: 198 files, 3768 passed, 10 skipped.
`pnpm --filter @objectstack/plugin-auth typecheck`: green, test layer
included. `pnpm --filter @objectstack/rest test`: 323 files, 6474
passed. `pnpm --filter @objectstack/rest typecheck`: green.
- The client suites that read the ledger as source
(`client-url-conformance`, `auth-route-ledger-coverage`,
`route-ledger-response-schema`): 3 files, 10 passed.
- The sweep classification, read statically with its own `classify`: the
new route classifies as door 2, the control `get-invitation` as `outside
control-plane-allowlist`, and class 2's expectation accepts the bare
probe's 400. The dogfood sweep itself is NOT MEASURED locally (it boots
the showcase on a full build); it runs with the `main` battery.
## Gates (local, on head `34e297bde`, after merging `origin/main`)
- `node scripts/pm/dispatch-gates.mjs --commands` on the real diff
derived 85 families. All 85 were run on this head, each exit code
captured before any pipe. All 85 exited 0. `--ran` reconciliation: "85
derived famil(ies) accounted for — 85 run, 0 NOT-MEASURED".
- `node scripts/check-auth-mount-ledger.mjs`: "22 ObjectStack auth
mount(s), all accounted for".
- The plugin-auth suite was re-run on this head after the closure
rebuild: 198 files, 3779 passed, 10 skipped. Typecheck green. The three
client ledger suites: 10 passed.
- `eslint --no-inline-config` over `packages/plugins/plugin-auth/src`,
`packages/rest/src/index.ts` and the sweep classification: clean.
- CI runs the full farm; its check-runs are the record.
## Acceptance notes
- The suite imports `createMemoryEngine` from
`impersonation-bearer-rotation.test.ts`, as
`admin-has-permission-endpoint.test.ts` does, rather than minting a new
engine double. That re-registers that file's nine cases inside this
file's run (about 4 s).
- A caller whose address the server cannot establish (no `trustProxy`,
no transport peer) counts in one shared window. That fails closed: such
callers can starve each other, but never escape the limit.
- `#25886` remains open for the UI half; Q2 B needs no code.
## 维护者速读(草稿)
**改了什么**:新增一个免登录的「邀请预览」只读接口。被邀请人还没登录时,打开邀请链接的页面可以显示「Alice 邀请你加入
Acme」,只给出组织名、邀请人名和打了码的邮箱(如 `b***@acme.test`)。
**为什么改**:按裁定 `6413975861`(Q1 A):被邀请人第一次打开链接只看到通用登录页,不知道是谁邀请、加入哪个组织。
**风险与代价(含回滚)**:这是一扇匿名可达的门。收紧措施:只认未过期的待处理邀请;其余五种状态一律同一个 404;每个地址每分钟最多 10
次;邮箱打码;不读会话。ADR-0138 D2 加了一条注记,把它登记为第 2 类形态的门。回滚:撤回本 PR 即可,无数据迁移。
**席位意见**:
**你要做的**:审阅 ADR-0138 的注记与接口形态;同意则批准并合并(Tier H)。
---
_Generated by [Claude
Code](https://claude.ai/code/session_01YSfdNdSer8xUQULiYH3Yq5)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent c7aa9cd commit 83a26c3
9 files changed
Lines changed: 668 additions & 2 deletions
File tree
- .changeset
- docs/adr
- packages
- plugins/plugin-auth/src
- qa/dogfood/test
- rest/src
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
25 | 25 | | |
26 | 26 | | |
27 | 27 | | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
28 | 32 | | |
29 | 33 | | |
30 | 34 | | |
| |||
276 | 280 | | |
277 | 281 | | |
278 | 282 | | |
| 283 | + | |
| 284 | + | |
| 285 | + | |
| 286 | + | |
| 287 | + | |
| 288 | + | |
| 289 | + | |
| 290 | + | |
| 291 | + | |
| 292 | + | |
| 293 | + | |
| 294 | + | |
| 295 | + | |
| 296 | + | |
| 297 | + | |
| 298 | + | |
| 299 | + | |
| 300 | + | |
| 301 | + | |
| 302 | + | |
279 | 303 | | |
280 | 304 | | |
281 | 305 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
530 | 530 | | |
531 | 531 | | |
532 | 532 | | |
| 533 | + | |
| 534 | + | |
533 | 535 | | |
534 | 536 | | |
535 | 537 | | |
| |||
701 | 703 | | |
702 | 704 | | |
703 | 705 | | |
| 706 | + | |
| 707 | + | |
| 708 | + | |
| 709 | + | |
| 710 | + | |
| 711 | + | |
| 712 | + | |
| 713 | + | |
| 714 | + | |
| 715 | + | |
| 716 | + | |
| 717 | + | |
704 | 718 | | |
705 | 719 | | |
706 | 720 | | |
| |||
3827 | 3841 | | |
3828 | 3842 | | |
3829 | 3843 | | |
| 3844 | + | |
| 3845 | + | |
| 3846 | + | |
| 3847 | + | |
| 3848 | + | |
| 3849 | + | |
| 3850 | + | |
| 3851 | + | |
| 3852 | + | |
| 3853 | + | |
| 3854 | + | |
| 3855 | + | |
| 3856 | + | |
| 3857 | + | |
| 3858 | + | |
| 3859 | + | |
| 3860 | + | |
| 3861 | + | |
| 3862 | + | |
| 3863 | + | |
| 3864 | + | |
| 3865 | + | |
| 3866 | + | |
| 3867 | + | |
| 3868 | + | |
| 3869 | + | |
| 3870 | + | |
| 3871 | + | |
| 3872 | + | |
| 3873 | + | |
| 3874 | + | |
| 3875 | + | |
| 3876 | + | |
| 3877 | + | |
| 3878 | + | |
3830 | 3879 | | |
3831 | 3880 | | |
3832 | 3881 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
215 | 215 | | |
216 | 216 | | |
217 | 217 | | |
| 218 | + | |
| 219 | + | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
| 223 | + | |
218 | 224 | | |
219 | 225 | | |
220 | 226 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
253 | 253 | | |
254 | 254 | | |
255 | 255 | | |
| 256 | + | |
| 257 | + | |
| 258 | + | |
| 259 | + | |
| 260 | + | |
| 261 | + | |
256 | 262 | | |
257 | 263 | | |
258 | 264 | | |
| |||
0 commit comments