Skip to content

Commit 83a26c3

Browse files
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
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
'@objectstack/plugin-auth': patch
3+
'@objectstack/rest': patch
4+
---
5+
6+
feat(plugin-auth): a signed-out invitation preview read, so the invitation landing page can name the inviting organization and the inviter
7+
8+
Clause-②: no
9+
Metadata-protocol: none
10+
11+
- **New route.** `GET /api/v1/auth/organization/invitation-preview?id=INVITATION_ID` answers a caller with no session. For a `pending` invitation that has not expired it returns exactly `{ success: true, data: { organizationName, inviterName, email } }`. `email` is the invited address masked to its first character and its domain (`alice@acme.com` becomes `a***@acme.com`), and `inviterName` is `null` when the inviter's account no longer exists.
12+
- **One not-found.** An unknown, expired, accepted, rejected or cancelled id answers the same `404` with code `RESOURCE_NOT_FOUND` and the same body, so the answer does not tell those states apart.
13+
- **The same answer for everyone.** The route never reads the session: a signed-in caller gets the identical three keys.
14+
- **Rate-limited.** At most 10 previews per client address per 60 seconds, counted before the request is parsed; the 11th answers `429` `RATE_LIMIT_EXCEEDED` with `Retry-After`. The window counts in the kernel `cache` service when one is registered and per process otherwise, with a one-time warning naming the budget.
15+
- **Closed query set.** `id`, once. Any other parameter, a repeated `id` and a missing `id` each answer a located `400` `VALIDATION_ERROR`.
16+
- **Unchanged.** better-auth's own `GET /organization/get-invitation` still answers `401` without a session, and an invitation-link sign-up still owes the verification mail.
17+
- **Governance.** ADR-0138 D2 admits the route as a class-2-shaped door (the invitation id is the capability token) by a dated note, and `auth-route-ledger.ts` books it `public`.
18+
- **`@objectstack/rest`** now exports `unknownQueryParamRefusalMessage`, the pure half of the closed query-parameter rule, for a door outside the package that writes its own envelope.

‎docs/adr/0138-guest-model-anonymous-principal-doors-grants-and-organization.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,10 @@ D11 are unchanged.
2525
maintainer 「23267 我们的系统 和 salesforce 类似,暂时没有 没有公开站点或门户的产品计划」) — D3 item 5: the
2626
guest's bind door is built implementation-first, when a named deployment needs to grant the guest on
2727
a public surface; until then no door binds a set to `guest`, and the record carries the door's shape.
28+
· **Amended** (2026-10-26, ruling Q1 A on [#26020](https://github.com/objectstack-ai/objectstack/issues/26020),
29+
[`6413975861`](https://github.com/objectstack-ai/objectstack/issues/26020#issuecomment-6413975861),
30+
maintainer 「26020 Q1 A Q2 B 26001 A」) — D2: the signed-out invitation preview is admitted as a
31+
class-2-shaped door ([the dated note under D2's table](#d2--the-closed-list-of-doors)).
2832
**Decided by**: the maintainer's ruling on [#22146](https://github.com/objectstack-ai/objectstack/issues/22146)
2933
(comment [`6054113537`](https://github.com/objectstack-ai/objectstack/issues/22146#issuecomment-6054113537),
3034
decision batch #290 item 1, 2026-10-08, 「22146 同意」): **A on all eight questions, and G2 on the
@@ -276,6 +280,26 @@ envelope does not carry, so the envelope the runtime face assembles for every se
276280
(D9) is refused in every domain except at the two endpoint classes above. A new surface is therefore
277281
401 until this list names it, and naming a new door class is an amendment of this record.
278282

283+
**Amended 2026-10-26 — the signed-out invitation preview, a class-2-shaped door.** Ruling Q1 A on
284+
[#26020](https://github.com/objectstack-ai/objectstack/issues/26020)
285+
([`6413975861`](https://github.com/objectstack-ai/objectstack/issues/26020#issuecomment-6413975861),
286+
maintainer 「26020 Q1 A Q2 B 26001 A」) admits one more door of class 2's shape, not a seventh class:
287+
`GET /api/v1/auth/organization/invitation-preview?id=…`, so the invitation landing page can name the
288+
inviting organization and the inviter to a person who is not signed in. What admits the request: the
289+
invitation id the invitation link carries, the capability token. What it runs as: after validation,
290+
a read of that one invitation, projected — it answers only for a `pending` invitation that has not
291+
expired, returns exactly `{ organizationName, inviterName, email }` with the invited address masked,
292+
and gives one uniform not-found for an unknown, expired, accepted, rejected or cancelled id. No
293+
principal is evaluated and the session is never read, so a signed-in caller gets the same
294+
projection. It carries a per-address rate limit, as ADR-0121 D6 requires of a door that admits an
295+
anonymous caller. Enforced by
296+
`packages/plugins/plugin-auth/src/invitation-preview.ts#runInvitationPreview`, ledgered in
297+
`packages/plugins/plugin-auth/src/auth-route-ledger.ts`. The route sits in the `/auth` namespace,
298+
which the control-plane allowlist exempts as a whole; the sweep's classification therefore lists it
299+
under class 2, ahead of the allowlist, so it is judged as this door and not as control-plane
300+
infrastructure. The same ruling's Q2 B leaves the verification posture as it was: an
301+
invitation-link sign-up still owes the verification mail.
302+
279303
**Outside the guest model by construction**, and not on the list:
280304

281305
- the control-plane allowlist (`packages/core/src/security/auth-gate.ts#isAuthGateAllowlisted`:

‎packages/plugins/plugin-auth/src/auth-plugin.ts‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -530,6 +530,8 @@ export class AuthPlugin implements Plugin {
530530
* Memoized `bindAuthSettings()` run — see {@link ensureAuthSettingsBound}.
531531
*/
532532
private authSettingsBinding: Promise<void> | null = null;
533+
/** [#26020] The per-address window of the signed-out invitation preview counts here; set in `init()`. */
534+
private invitationPreviewCounters: (() => Promise<CounterStore>) | null = null;
533535

534536
constructor(options: AuthPluginOptions = {}) {
535537
this.options = {
@@ -701,6 +703,18 @@ export class AuthPlugin implements Plugin {
701703
'cooldown and hourly cap, so an N-node deployment can send up to N× the configured number of ' +
702704
'PAID SMS to one number',
703705
});
706+
// [#26020] The signed-out invitation preview's per-address window
707+
// (ADR-0121 D6: a door that admits an anonymous caller carries a rate
708+
// limit), on the same lazy resolution. Its own subject, so an operator
709+
// reading the degraded warning knows WHICH budget stopped being global.
710+
this.invitationPreviewCounters = createLazyCounterStore({
711+
resolveCache,
712+
logger: ctx.logger,
713+
subject: 'signed-out invitation preview rate limit',
714+
degradedImpact:
715+
'The limit is still enforced, but PER NODE: an N-node deployment admits up to N× the configured ' +
716+
'previews per address per window',
717+
});
704718
}
705719

706720
this.applyEnvSocialProviderFallbacks(authConfig);
@@ -3827,6 +3841,41 @@ export class AuthPlugin implements Plugin {
38273841
}
38283842
});
38293843

3844+
// ────────────────────────────────────────────────────────────────────
3845+
// [#26020] The signed-out invitation preview (ruling 6413975861, Q1 A):
3846+
// `{ organizationName, inviterName, email }` with the address masked, for
3847+
// a pending, unexpired invitation only, one uniform not-found for every
3848+
// other id, rate-limited per address. An anonymous door: ADR-0138 D2's
3849+
// dated note admits it as a class-2-shaped door (the invitation id is the
3850+
// capability token), and the reasons for each of those properties live in
3851+
// invitation-preview.ts. It never reads the session, so a signed-in caller
3852+
// gets the same projection. Ledgered `public` in auth-route-ledger.ts.
3853+
rawApp.get(`${basePath}/organization/invitation-preview`, async (c: any) => {
3854+
try {
3855+
const counters = this.invitationPreviewCounters;
3856+
const mgr = this.authManager!;
3857+
if (!counters) {
3858+
ctx.logger.error('[AuthPlugin] organization/invitation-preview: the rate-limit store was never wired; refusing');
3859+
return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: 'The invitation preview is unavailable.' } }, 500);
3860+
}
3861+
const { runInvitationPreview } = await import('./invitation-preview.js');
3862+
const headers = (c.req.header() ?? {}) as Record<string, string>;
3863+
const answer = await runInvitationPreview(
3864+
{
3865+
queries: (c.req.queries() ?? {}) as Record<string, string[]>,
3866+
clientAddress: mgr.resolveClientAddress({ headers, ...transportOf(c) }),
3867+
},
3868+
{ getDataEngine: () => mgr.getDataEngine() as any, counterStore: counters },
3869+
);
3870+
return c.json(answer.body, answer.status as any, answer.headers);
3871+
} catch (error) {
3872+
const err = error instanceof Error ? error : new Error(String(error));
3873+
ctx.logger.error('[AuthPlugin] organization/invitation-preview failed', err);
3874+
// A signed-out caller is told the read failed, never why.
3875+
return c.json({ success: false, error: { code: 'INTERNAL_ERROR', message: 'The invitation preview is unavailable.' } }, 500);
3876+
}
3877+
});
3878+
38303879
// ────────────────────────────────────────────────────────────────────
38313880
// ADR-0069 P3 — register a SAML 2.0 IdP. Mirrors the OIDC bridge above:
38323881
// the metadata `register_saml_provider` action posts FLAT fields; the shared

‎packages/plugins/plugin-auth/src/auth-route-ledger.conformance.test.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -215,6 +215,12 @@ describe('auth route ledger hygiene', () => {
215215
expect(own).toEqual([
216216
'GET /api/v1/auth/bootstrap-status',
217217
'GET /api/v1/auth/config',
218+
// [#26020] On this pin's own terms: `auth-plugin.ts` mounts it itself (a
219+
// `rawApp.get` on the `${basePath}/organization/invitation-preview`
220+
// template, ahead of the catch-all), and the `live.has(route)` loop below
221+
// holds it to the same proof — better-auth's own read is
222+
// `/organization/get-invitation`, a different path.
223+
'GET /api/v1/auth/organization/invitation-preview',
218224
'POST /api/v1/auth/admin/import-users',
219225
'POST /api/v1/auth/admin/oauth2/toggle-disabled',
220226
// [#16678] The thirteenth, added on this pin's own terms exactly as the

‎packages/plugins/plugin-auth/src/auth-route-ledger.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -253,6 +253,12 @@ export const AUTH_ROUTE_LEDGER: readonly AuthRouteLedgerEntry[] = [
253253
// restores the URL the `sys_member` `add_member` toolbar action has always
254254
// targeted (on multi-org the only UI path to attach an existing user).
255255
{ route: 'POST /api/v1/auth/organization/add-member', family: 'organization', source: 'objectstack', disposition: 'server-only', requires: 'organization', note: 'no SDK method builds this URL — the sys_member add_member action posts it directly; ObjectStack mount wrapping the vendor server-only auth.api.addMember, platform-admin gated (ADR-0068); on multi-org it is the only UI path that attaches an existing user to an organization' },
256+
// #26020 (ruling 6413975861, Q1 A) — the tracker id stays HERE and never in
257+
// the `note` string, per the #16678 note above. `public` is this file's word
258+
// for "unauthenticated, browser-facing", and the first row to carry it: the
259+
// Console's signed-out invitation landing page reads it, and no SDK method
260+
// builds it.
261+
{ route: 'GET /api/v1/auth/organization/invitation-preview', family: 'organization', source: 'objectstack', disposition: 'public', requires: 'organization', note: 'the signed-out invitation preview: answers a caller with NO session, keyed by the invitation id the link carries (a capability token, ADR-0138 D2 class-2-shaped door by its dated note). Returns exactly { organizationName, inviterName, email } with the address masked, for a pending, unexpired invitation only; one uniform 404 for an unknown, expired, accepted, rejected or cancelled id; a fixed per-address rate limit (ADR-0121 D6); closed query set { id }. The vendor GET /organization/get-invitation answers 401 without a session and is unchanged' },
256262
{ route: 'POST /api/v1/auth/organization/add-team-member', family: 'organization', source: 'better-auth', disposition: 'sdk', client: 'organizations.teams.addMember', requires: 'organization' },
257263
{ route: 'POST /api/v1/auth/organization/cancel-invitation', family: 'organization', source: 'better-auth', disposition: 'sdk', client: 'organizations.invitations.cancel', requires: 'organization' },
258264
{ route: 'POST /api/v1/auth/organization/create', family: 'organization', source: 'better-auth', disposition: 'sdk', client: 'organizations.create', requires: 'organization' },

0 commit comments

Comments
 (0)