Skip to content

ADR (mirror of cloud ADR-0071): env-side SCIM via @better-auth/scim — the open mechanism half (D1–D4), recorded in this repo with Provenance and the measured 1.7.x vendor drift #14507

Closed
#16476
Closed
ADR (mirror of cloud ADR-0071): env-side SCIM via @better-auth/scim — the open mechanism half (D1–D4), recorded in this repo with Provenance and the measured 1.7.x vendor drift#14507
#16476
Labels
documentationImprovements or additions to documentationdomain:servicespriority:p2Medium: important, M3

Description

@hotlong
hotlong
opened on Sep 2, 2026

Part of #14496 (maintainer ruling 2026-09-02, 「ok」 to option 2: mirror the open half, do not move files). Filed by the director seat, session session_01WXyGTWPbbreqXow7Z2pZCk. docs/adr/** is a governed surface: draft PR, human merge. Clause-②: no. domain:* is triage's.

What to write

A new local ADR (next free number) that states, as this repo enforces them, the decisions of cloud docs/adr/0071-enterprise-identity-scim-v1.md (Status: Proposed, founder to accept; 2026-06-27; entered this repo through PR #2356) whose mechanism is open code. From the cloud record's own headings, the open half is:

  • D1 adopt @better-auth/scim as the mechanism, do not build a SCIM server;
  • D2 the SCIM Service Provider lives in the env, never in the cloud (identical for cloud-managed and self-host);
  • D3 single-organization mode; deactivate via active:false, never DELETE — deprovision removes membership and keeps the user record; deactivation = account disabled + session revocation;
  • D4 V1 provisions a default role; group→role mapping deferred behind a seam;
  • the open part of D7: the SCIM conformance / smoke test in CI.

Stays in cloud, cited as cloud ADR-0071: D5 open/closed boundary (mechanism open, governance closed), D6 commercial repositioning (paid = governed / supported / audited SCIM), the real-IdP E2E in cloud's staging, the Enterprise Identity pillar framing.

One fact the mirror must state honestly (measured, #14360)

The cloud record says deactivation is "active:false → ban (via the admin plugin) + session revocation" — true of @better-auth/scim 1.6.x, removed upstream in 1.7.0: at the pinned 1.7.2 the vendor calls an optional host hook identity.reconcileUser and revokes sessions, and writes no ban. #14360 (limb A, dispatched at CONTRACT_REVIEW_TIER) restores the decision through this platform's own ban write (admin-ban-endpoints.ts, last-admin guard included). The mirror records D3 as this platform's enforcement — the ban is written by this repo's hook, not assumed from the vendor — and names the vendor-version fact, so the 39 comments that currently say "runs through the better-auth admin plugin (ADR-0071)" have a true sentence to be re-pointed at. ⛔ Do not wait for #14360's PR to write the record; do state which side writes the ban.

Shape (copy docs/adr/0079-record-display-name.md)

## Provenance — read this before citing this file first (original decision in objectstack-ai/cloud ADR-0071, 2026-06-27; commercial half stays there; this file written from the cloud record and the implementing code — packages/plugins/plugin-auth/src/auth-manager.ts scim({...}) options, assertScimAdminCoherence, packages/platform-objects/src/identity/sys-scim-*.object.ts, packages/spec/src/system/auth-config.zod.ts plugins.scim / plugins.admin describe strings). Decisions restated with their code anchors; ⛔ nothing decided that the cloud record did not decide.

Follow-ups the accepting seat files (not this card)

Refs: #14496 · #14361 · #14360 · #13816 · #14150 · cloud ADR-0071 · ADR-0079.

Activity

  1. hotlong
    added
    documentationImprovements or additions to documentation
    pm:queue
    on Sep 2, 2026
  2. hotlong
    added a parent issue on Sep 2, 2026
  3. os-zhuang
    added
    priority:p2Medium: important, M3
    domain:services
    on Sep 4, 2026

  4. os-zhuang commented on Sep 4, 2026

    @os-zhuang
    os-zhuang
    on Sep 4, 2026 – with Claude
    Contributor

    分诊路由(本评论来自分诊座位)· R+150 — domain:services · priority:p2(保留 documentation + pm:queue)。

    判据(实测,⛔ 非按标题猜):git grep -li "scim" -- packages/plugins 得 plugin-auth 31 命中,其余插件 ≤2;SCIM 机制源文件在 packages/plugins/plugin-auth/src/(scim-connection-service.ts、scim-case-insensitive-identifier.test.ts、scim-deactivation-reconcile-user.test.ts、scim-transaction-scope.test.ts)⇒ 机制半边整个在 services 车道。

    三份镜像同车道的理由与 p2 判据见父单 #14496 评论 5545404025。受管面 ⇒ draft PR + 人工合并。⚠️ 卡面点名的那条必须诚实写出的事实(1.7.0 起 vendor 不再写 ban,由本仓自己的 hook 写)是本卡的实质内容,⛔ 别当成背景删掉。

    Generated by Claude Code

  5. os-warren commented on Sep 7, 2026

    @os-warren
    os-warren
    on Sep 7, 2026 – with Claude
    Collaborator

    Claim: domain:services PM seat · session session_01XpTx2tbq3pZRYAdoGt6E6Y · 2026-09-07

    分支 claude/issue-14507-adr-mirror-scim-env-side · worktree objectstack-issue-14507
    Clause-②: no（卡面自陈；diff 不会碰 packages/spec/**）

    ⛔ 受管面：交付物在 docs/adr/**。draft PR + 人工合并，⛔ 席位不 flip ready、⛔ PM 不 arm auto-merge。

    派发前 PM 实测（⛔ 不是按卡面复述）

    Refs: #14496（裁定）· #14361 · #14360 · ADR-0079（Provenance 体例）

    Generated by Claude Code

  6. os-warren commented on Sep 7, 2026

    @os-warren
    os-warren
    on Sep 7, 2026 – with Claude
    Collaborator

    os-dev-report

    {
  "issue": 14507,
  "status": "done",
  "branch": "claude/issue-14507-adr-mirror-scim-env-side",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/16476",
  "pr_number": 16476,
  "pr_state": "DRAFT (verified by reading the PR page back: \"state\":\"DRAFT\"; never flipped ready, never enqueued, auto-merge never armed)",
  "head_sha": "5b987ca643d9854c1b85a61c5ec5ef3d16691313",
  "adr_file": "docs/adr/0134-env-side-scim-provisioning.md",
  "adr_number_check": "0134 was free. origin/main (5a9138703) tops out at 0131; remote head claude/issue-14508-adr-org-management-open-basics adds docs/adr/0133-org-management-open-basics.md (PR #16267), confirming 0133 taken; claude/issue-14506-adr-mirror-identity-access is still at the base commit with no ADR yet (0132 unwritten). No stop-and-report needed.",
  "premise_still_valid": true,
  "summary": "Wrote one new record, docs/adr/0134-env-side-scim-provisioning.md (312 lines, the only file in the diff), mirroring the open mechanism half of cloud ADR-0071 in this repo's own words per the maintainer's 2026-09-02 ruling on #14496. It restates D1 (adopt @better-auth/scim, bridge its seven models to sys_scim_* platform objects), D2 (the Service Provider lives in the env, tri-state plugins.scim / OS_SCIM_ENABLED, connections are runtime data behind an app-owned bearer verifier), D3 (single-organization; active:false disables + revokes sessions, DELETE never erases the user), D4 (default standing only; group-to-role is a declared, unwired seam on both the vendor and the platform side) and the open half of D7 (the SCIM coverage that runs in this repo's CI, named file by file). D5, D6, the real-IdP E2E and the Enterprise Identity pillar framing are explicitly left in cloud and cited as `cloud ADR-0071`. Every clause carries a symbol anchor; nothing is decided that the cloud record did not decide. The Provenance section additionally records that docs/adr/0071-* in THIS repo is the unrelated Dataset semantic-layer depth record, so a bare ADR-0071 in identity code resolves to the wrong document (that repair stays #14361's).",
  "vendor_measurement": {
    "how": "measured first-hand in this worktree, not copied from the card: read the lockfile pin, read the installed package in node_modules, and additionally downloaded 1.6.30 / 1.7.0 / 1.7.1 tarballs from the registry so the 'removed in 1.7.0' half is my own reading too",
    "pinned_version": "1.7.2 — packages/plugins/plugin-auth/package.json declares ^1.7.2, pnpm-lock.yaml resolves @better-auth/scim@1.7.2, and the installed package's own package.json reports 1.7.2",
    "ban_occurrences_in_dist_index_mjs": { "1.6.30": 14, "1.7.0": 0, "1.7.1": 0, "1.7.2": 0 },
    "1.6.31": "registry 404 — 1.6.30 is the last 1.6.x, so the 1.6.x reading is on the final 1.6 release",
    "1_6_30_detail": "resolveSCIMActiveDeactivation sets banned: true and banReason to the literal 'Deactivated via SCIM'",
    "1_7_2_detail": "the reconciliation path calls the OPTIONAL host hook options.identity?.reconcileUser?.(state, { database }) and then, when the aggregate is inactive, awaits auth.internalAdapter.deleteUserSessions(userId). It writes no ban.",
    "ban_ownership_conclusion": "THIS REPO writes the ban, not the vendor. auth-manager.ts#reconcileScimUserLifecycle implements the host hook and lands the disable through user-ban-write.ts#applyUserBan with user-ban-write.ts#SCIM_DEACTIVATION_BAN_REASON — field for field the write admin-ban-endpoints.ts#runAdminBanUser makes — judged at the engine by last-admin-guard.ts#registerLastAdminGuard. The admin plugin is still required because it supplies the column and the BANNED_USER sign-in refusal (which is what keeps assertScimAdminCoherence coherent). Session revocation stayed with the vendor.",
    "agrees_with_card": "yes, in every particular. Nothing to smooth over.",
    "note": "#14360's wiring is already on origin/main, so the record did not have to wait on it and does not defer to it."
  },
  "governed_verdicts": {
    "positive": "node scripts/pm/check-governed-merges.mjs --test docs/adr/0134-env-side-scim-provisioning.md -> EXIT=3, verdict line: 'GOVERNED — a human merge is the review record for this PR (#9495 regime)', 'docs/adr/** x1 — architecture decision records'",
    "negative_control": "node scripts/pm/check-governed-merges.mjs --test packages/plugins/plugin-auth/src/auth-manager.ts -> EXIT=0, verdict line: 'NOT governed — ordinary queue landing applies to a PR with exactly this file list'"
  },
  "anchors_verified": "every anchor the card named was opened on this branch and confirmed to exist AND to say what the card said: auth-manager.ts's scim({...}) options block (connections / authentication.verifyBearerToken / identity.reconcileUser, and NO projection member), assertScimAdminCoherence, packages/platform-objects/src/identity/sys-scim-*.object.ts (all eight), and the plugins.scim / plugins.admin describe strings in packages/spec/src/system/auth-config.zod.ts. Nothing was off. Anchors are written in symbol-anchor form and pnpm check:adr-symbol-anchors resolves all of them (2013 anchors across 136 records, 0 line anchors survive).",
  "clause_2": "no — packages/spec/src/system/auth-config.zod.ts was READ as an anchor and is NOT in the diff. Nothing there needed changing, so there was nothing to stop and report.",
  "changeset": "none — skip-changeset. Basis measured in-repo, not recalled: the four most recent docs/adr/**-only landings (245c6a23c, 932acc3df, 3a534facb, e6c99643e) each land the ADR alone with no .changeset/*.md. The label IS applied on PR #16476 — see the label caveat below.",
  "tests": "Docs-only diff; no package test suite is in scope. Gate family derived MECHANICALLY at head 5b987ca64 with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands` (derivation exit 0; change set 1 path from the merge base, three-dot). 17 commands, ALL RUN, ALL GREEN, each exit code captured with `cmd > log 2>&1; EXIT=$?` before any pipe. (1) node scripts/check-adr-links.mjs EXIT=0 — '654 relative link destination(s) under docs/adr/ resolve'. (2) --self-test EXIT=0. (3) node scripts/check-adr-symbol-anchors.mjs EXIT=0 — '2013 anchors across 136 records resolve ... 0 line anchors survive'. (4) --self-test EXIT=0. (5) check-ci-filter-parity EXIT=0. (6) check-closing-keyword-parity EXIT=0. (7) its --self-test EXIT=0. (8) check-comment-mask-corpus EXIT=0 — '6250 files, 0 disagree'. (9) pnpm --filter @objectstack/lint run check:doc-formula-expressions EXIT=3 FIRST = PREREQUISITE NOT MET, NOT MEASURED, NOT a finding (the gate imports compiled @objectstack/formula and @objectstack/lint output); after `turbo run build --filter=@objectstack/formula --filter=@objectstack/lint` under the shared verify lock (VERDICT command-exit 0), re-run EXIT=0 — '14 predicate(s) judged clean; 6 skipped as undeterminable'. (10) pnpm check:adr-anchors EXIT=0 (only pre-existing allowlisted notes). (11) check:cross-package-test-inputs EXIT=0. (12) check:doc-authoring EXIT=0. (13) check:driver-memory-census EXIT=0. (14) check:nul-bytes EXIT=0 — '8084 text file(s) ... no raw ASCII control bytes'. (15) check:pm-governed-merges EXIT=0. (16) check:refd-timer-probe EXIT=0. (17) check:watch-hint-literal EXIT=0. Additionally scanned the new file directly for raw control bytes (grep -naP over the C0 set): no match. The whole-tree families, the 3 workflow-valued families and the 41 artifact rosters that dispatch-gates declares unplaceable are reported as NOT MEASURED, not as green — CI runs the farm.",
  "mcp_calls": "4 — create_pull_request, issue_read/get_labels (failed: 'Could not resolve to an Issue'), issue_write/update (labels), add_issue_comment (this one). Issue and PR reads went through the zero-quota public-repo payload/page channel; the container's REST channel is session-gated 403 for the whole repo-scoped class (probed once at the top of the run and again on the label endpoint).",
  "open_questions": [],
  "out_of_scope_findings": [
    "NOT FILED — handed to PM for triage, because it overlaps #14361/#14360's territory and I did not want to mint a near-duplicate: packages/plugins/plugin-auth/src/auth-manager.ts, in the comment block immediately above the scim({...}) call, still says 'the installed 1.7.1' while the lockfile pins 1.7.2 (the SAME function's #14360 comment 30 lines below says 'measured on 1.7.2'), and the same block still summarises deactivation as 'active:false -> ban + session revoke (needs the admin plugin, forced on above)', which reads as the vendor writing the ban. scripts/check-vendor-version-stamps.mjs already watches @better-auth/scim version stamps, so this is a live gate's blind corner rather than free-form prose. Say the word and I will file it."
  ],
  "caveats_for_pm": [
    "LABEL WRITE WAS NOT ADDITIVE — read back and it is fine, but PM should know the shape. REST is session-gated 403 here (POST /repos/.../issues/16476/labels returns 'GitHub access is not enabled for this session'), and MCP has no additive PR-label path: issue_read/get_labels refuses a PR number ('Could not resolve to an Issue with the number of 16476'), and update_pull_request carries no labels field. The only route that worked was issue_write method=update with labels, which REPLACES the whole set — and I could not read the prior set first, because the read half refuses PR numbers. Read-back on the PR page now shows THREE label chips: documentation, size/m, skip-changeset. So the end state is correct (the automation labels are present alongside mine), but the write itself was a whole-set replace made blind. ⚠️ If a governance-gating label is ever expected on an ADR PR from this seat, verify it explicitly rather than trusting this path.",
    "issue_write on a PR number did NOT touch the draft bit (it goes through the Issues API, which has no draft field) — re-read the PR page after the label write and it still reports \"state\":\"DRAFT\".",
    "Nothing in the card or the PM brief was wrong. The one thing the brief left open — whether 0134 was still free — I checked against origin/main and against every remote head, and it is."
  ]
}

    Generated by Claude Code

  7. os-zhuang
    closed this as completedin #16476on Sep 7, 2026
  8. github-actions
    removed
    pm:queue
    on Sep 7, 2026

  9. github-actions commented on Sep 7, 2026

    @github-actions
    github-actionsbot
    on Sep 7, 2026 – with GitHub Actions
    Contributor

    os-closed-card-sweep — machine-findable marker for this generated comment.

    Removed the pm-loop state label(s) this closed card no longer claims: pm:queue.

    A state label claims work is in flight. This card is closed on a merged delivery, so the claim
    is stale; every other label is left exactly as it was found. Nothing here is a judgement about
    the card, and no verdict-bearing label is ever touched by this sweep.

    posted by half-state-patrol run 34097314575 · trigger schedule

    Generated by Claude Code

  10. akarma-synetal
    added a commit that references this issue on Sep 17, 2026

    docs(identity): re-point the SCIM/identity ADR-0071 citations at the …

    825d70f
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationdomain:servicespriority:p2Medium: important, M3

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions