SCIM 2.0 Inbound Provisioning — Implementation Plan

-- +goose Up
-- SCIM 2.0 inbound provisioning (RFC 7643/7644). DISABLED by default: with no minted token
-- every /scim/v2 request is 401 and these tables stay empty, so the demo and every existing
-- deployment are byte-for-byte unchanged until an admin generates a token.

-- Admin-minted bearer tokens that authenticate the IdP's SCIM client. Only sha256(token) is
-- stored; the raw token is shown ONCE at mint time. "One active token" is enforced by the
-- partial unique index below (at most one row with revoked_at IS NULL); minting a new token
-- revokes the prior active one. Presence of an active token == SCIM enabled.
CREATE TABLE scim_tokens (
    id           uuid PRIMARY KEY,
    token_hash   text NOT NULL,
    created_at   timestamptz NOT NULL DEFAULT now(),
    created_by   uuid REFERENCES users(id) ON DELETE SET NULL,
    last_used_at timestamptz,
    revoked_at   timestamptz
);
CREATE UNIQUE INDEX scim_tokens_one_active ON scim_tokens (revoked_at) WHERE revoked_at IS NULL;

-- SCIM Group resources pushed by the IdP. id is the Obscura-side resource id (the SCIM {id});
-- external_id correlates to the IdP's own group id; display_name is the SCIM displayName.
CREATE TABLE scim_groups (
    id           uuid PRIMARY KEY,
    external_id  text,
    display_name text NOT NULL,
    created_at   timestamptz NOT NULL DEFAULT now(),
    updated_at   timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX scim_groups_display_name ON scim_groups (lower(display_name));

-- Pushed group membership (SCIM Group.members -> Obscura users). Cascades on group/user delete.
CREATE TABLE scim_group_members (
    group_id uuid NOT NULL REFERENCES scim_groups(id) ON DELETE CASCADE,
    user_id  uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    PRIMARY KEY (group_id, user_id)
);
CREATE INDEX scim_group_members_user ON scim_group_members (user_id);

-- +goose Down
DROP TABLE scim_group_members;
DROP TABLE scim_groups;
DROP TABLE scim_tokens;

-- +goose Up
-- Admin-managed SCIM-group -> Obscura-role mapping. Keyed by the SCIM group id (one role per
-- group, mirroring ldap_group_roles' one-role-per-DN). role_id references the rbac roles
-- catalogue (roles.id is uuid). ON DELETE CASCADE from both the group and the role.
CREATE TABLE scim_group_roles (
    scim_group_id uuid PRIMARY KEY REFERENCES scim_groups(id) ON DELETE CASCADE,
    role_id       uuid NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
    created_at    timestamptz NOT NULL DEFAULT now()
);

-- Ledger of role bindings CREATED by SCIM group->role reconciliation, so they can be revoked
-- when a user leaves a mapped group WITHOUT touching manually-assigned roles (which have no
-- ledger row). One row per (user, role); scim_group_id records which mapping granted it.
-- Deliberately SEPARATE from ldap_role_grants: different source, different trigger, same rbac
-- binder (a role granted by both LDAP and SCIM has one row in each ledger, no conflict).
CREATE TABLE scim_role_grants (
    user_id       uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    role_id       uuid NOT NULL REFERENCES roles(id) ON DELETE CASCADE,
    scim_group_id uuid NOT NULL REFERENCES scim_groups(id) ON DELETE CASCADE,
    granted_at    timestamptz NOT NULL DEFAULT now(),
    PRIMARY KEY (user_id, role_id)
);
CREATE INDEX scim_role_grants_user ON scim_role_grants (user_id);

-- +goose Down
DROP TABLE scim_role_grants;
DROP TABLE scim_group_roles;

// Package domain holds the SCIM context's value types: the minted-token record, the pushed
// Group resource, the admin group->role mapping, and the reconciliation-ledger entry. Users
// are NOT modeled here — a SCIM user IS an auth `users` row (provider='scim'), accessed via the
// app-layer UserPort; SCIM only owns groups, tokens, mappings, and the grant ledger.
package domain

import "time"

// Token is a minted SCIM bearer token record. Only the sha256 hash is persisted (never the raw
// token, which is shown once at mint time). A token is active while RevokedAt is nil.
type Token struct {
    ID         string
    CreatedAt  time.Time
    CreatedBy  string
    LastUsedAt *time.Time
    RevokedAt  *time.Time
}

// Group is a SCIM Group resource pushed by the IdP. ID is the Obscura-side resource id (also the
// SCIM {id}); ExternalID correlates to the IdP's group id; DisplayName is the SCIM displayName.
type Group struct {
    ID          string
    ExternalID  string
    DisplayName string
    CreatedAt   time.Time
    UpdatedAt   time.Time
}

// GroupRoleMapping is one admin-managed SCIM-group -> Obscura-role mapping.
type GroupRoleMapping struct {
    ScimGroupID string
    RoleID      string
}

// RoleGrant is one reconciliation-ledger entry: a role granted to a user because they are a
// member of a mapped group. ScimGroupID records which mapping granted it.
type RoleGrant struct {
    RoleID      string
    ScimGroupID string
}

// Package app is the SCIM use-case layer: token mint/verify, user provisioning (via the narrow
// UserPort over the auth service), and group->role reconciliation (via the rbac RoleBinder).
package app

import (
    "context"
    "time"

    "github.com/Virtue-Digital-Indonesia/obscura/internal/scim/domain"
)

// subjectKindUser mirrors rbacapp.SubjectUser ("user") — the subject kind for a per-user role
// binding. Duplicated here so the scim context does not import rbac's app package.
const subjectKindUser = "user"

// ScimUser is the SCIM-projected view of a provisioned auth `users` row (+ its scim identity
// subject as ExternalID), so the scim context never imports auth's domain package. Read from
// the `users`/`user_identities` tables by the Store; written via the UserPort (auth service).
type ScimUser struct {
    ID          string
    Email       string
    DisplayName string
    ExternalID  string // user_identities.subject for idp='scim' ("" if none)
    Disabled    bool
}

// UserPort is the narrow WRITE slice of the auth service SCIM provisioning needs, so account
// mutation reuses the audited auth paths (JIT create with an scim identity, disable,
// session-revoke, profile update) rather than writing users/sessions directly. READS go through
// the Store (cross-table reads of users/user_identities). Implemented by a wire.go adapter over
// *authapp.Service.
type UserPort interface {
    // Provision creates-or-fetches the provider='scim' user for (externalID) with the given
    // email/name and returns the Obscura user id. Wraps auth.ProvisionLocal(idp="scim",
    // subject=externalID) — which writes user_identities(idp='scim', subject=externalID).
    Provision(ctx context.Context, externalID, email, name string) (userID string, err error)
    // SetDisabled flips the disabled flag (deprovision/restore).
    SetDisabled(ctx context.Context, userID string, disabled bool) error
    // RevokeSessions signs the user out everywhere (on deprovision) — auth.LogoutAll.
    RevokeSessions(ctx context.Context, userID string) error
    // UpdateProfile updates display name and/or email (PUT/PATCH); a nil field is unchanged.
    UpdateProfile(ctx context.Context, userID string, displayName, email *string) error
}

// RoleBinder is the narrow slice of the rbac write-service SCIM needs to apply group-derived
// role grants. *rbacadapters.Store satisfies it (BindRole/UnbindRole/RefreshEffectivePerms).
type RoleBinder interface {
    BindRole(ctx context.Context, roleID, subjectKind, subjectID string) error
    UnbindRole(ctx context.Context, roleID, subjectKind, subjectID string) error
    RefreshEffectivePerms(ctx context.Context) error
}

// Store persists the SCIM-owned tables: tokens, groups, group members, admin mappings, and the
// reconciliation ledger. Implemented by scimadapters.Store over Postgres.
type Store interface {
    // --- tokens ---
    InsertToken(ctx context.Context, id, tokenHash, createdBy string) error
    RevokeActiveTokens(ctx context.Context) error
    ActiveTokenHashes(ctx context.Context) ([]string, error)
    TouchToken(ctx context.Context, tokenHash string) error
    TokenStatus(ctx context.Context) (enabled bool, lastUsedAt *time.Time, err error)

    // --- groups ---
    InsertGroup(ctx context.Context, g domain.Group) error
    UpdateGroup(ctx context.Context, id, displayName, externalID string) error
    GetGroup(ctx context.Context, id string) (domain.Group, bool, error)
    GroupByDisplayName(ctx context.Context, displayName string) (domain.Group, bool, error)
    ListGroups(ctx context.Context, offset, limit int) (groups []domain.Group, total int, err error)
    DeleteGroup(ctx context.Context, id string) error

    // --- members ---
    ListMembers(ctx context.Context, groupID string) (userIDs []string, err error)
    AddMember(ctx context.Context, groupID, userID string) error
    RemoveMember(ctx context.Context, groupID, userID string) error
    ReplaceMembers(ctx context.Context, groupID string, userIDs []string) error
    GroupIDsForUser(ctx context.Context, userID string) ([]string, error)

    // --- admin mappings ---
    ListMappings(ctx context.Context) ([]domain.GroupRoleMapping, error)
    UpsertMapping(ctx context.Context, scimGroupID, roleID string) error
    DeleteMapping(ctx context.Context, scimGroupID string) error

    // --- reconciliation ledger ---
    GrantsForUser(ctx context.Context, userID string) ([]domain.RoleGrant, error)
    InsertGrant(ctx context.Context, userID, roleID, scimGroupID string) error
    DeleteGrant(ctx context.Context, userID, roleID string) error

    // --- user reads (read-only cross-table reads of users/user_identities) ---
    // GetProvisionedUser returns a provider='scim' user by id.
    GetProvisionedUser(ctx context.Context, userID string) (ScimUser, bool, error)
    // UserByEmail returns the oldest provider='scim' user with this email.
    UserByEmail(ctx context.Context, email string) (ScimUser, bool, error)
    // UserByExternalID returns the user linked to (idp='scim', subject=externalID).
    UserByExternalID(ctx context.Context, externalID string) (ScimUser, bool, error)
    // ListProvisionedUsers returns a page of provider='scim' users + the total.
    ListProvisionedUsers(ctx context.Context, offset, limit int) ([]ScimUser, int, error)
    // EmailExists reports whether ANY user (any provider) has this email — SCIM create dedups
    // against it so provisioning can't collide with a local/oidc/ldap account.
    EmailExists(ctx context.Context, email string) (bool, error)

    // --- status ---
    ProvisionedUserCount(ctx context.Context) (int, error)
}

// Package adapters implements the scim app ports against Postgres. Every statement runs through
// s.db.Exec(ctx) (no own tx except ReplaceMembers), mirroring the other Obscura stores.
package adapters

import (
    "context"
    "errors"
    "fmt"

    "github.com/jackc/pgx/v5"

    "github.com/Virtue-Digital-Indonesia/obscura/internal/platform/db"
    "github.com/Virtue-Digital-Indonesia/obscura/internal/scim/app"
    "github.com/Virtue-Digital-Indonesia/obscura/internal/scim/domain"
)

// Store implements app.Store over the scim_* tables.
type Store struct {
    db *db.DB
}

// NewStore constructs the SCIM repository.
func NewStore(d *db.DB) *Store { return &Store{db: d} }

// --- tokens ---

// InsertToken records a minted token (only its sha256 hash).
func (s *Store) InsertToken(ctx context.Context, id, tokenHash, createdBy string) error {
    var by any
    if createdBy != "" {
        by = createdBy
    }
    if _, err := s.db.Exec(ctx).Exec(ctx,
        `INSERT INTO scim_tokens (id, token_hash, created_by) VALUES ($1, $2, $3)`, id, tokenHash, by); err != nil {
        return fmt.Errorf("scim insert token: %w", err)
    }
    return nil
}

// RevokeActiveTokens marks every non-revoked token revoked (rotate / disable).
func (s *Store) RevokeActiveTokens(ctx context.Context) error {
    if _, err := s.db.Exec(ctx).Exec(ctx,
        `UPDATE scim_tokens SET revoked_at = now() WHERE revoked_at IS NULL`); err != nil {
        return fmt.Errorf("scim revoke tokens: %w", err)
    }
    return nil
}

// ActiveTokenHashes returns the hash(es) of every non-revoked token (normally 0 or 1). The app
// constant-time-compares the presented hash against these.
func (s *Store) ActiveTokenHashes(ctx context.Context) ([]string, error) {
    rows, err := s.db.Exec(ctx).Query(ctx, `SELECT token_hash FROM scim_tokens WHERE revoked_at IS NULL`)
    if err != nil {
        return nil, fmt.Errorf("scim active token hashes: %w", err)
    }
    defer rows.Close()
    var out []string
    for rows.Next() {
        var h string
        if err := rows.Scan(&h); err != nil {
            return nil, fmt.Errorf("scim scan token hash: %w", err)
        }
        out = append(out, h)
    }
    return out, rows.Err()
}

// TouchToken bumps last_used_at for the active token matching the hash.
func (s *Store) TouchToken(ctx context.Context, tokenHash string) error {
    if _, err := s.db.Exec(ctx).Exec(ctx,
        `UPDATE scim_tokens SET last_used_at = now() WHERE token_hash = $1 AND revoked_at IS NULL`, tokenHash); err != nil {
        return fmt.Errorf("scim touch token: %w", err)
    }
    return nil
}

// TokenStatus reports whether an active token exists and its last_used_at (most recent).
func (s *Store) TokenStatus(ctx context.Context) (bool, *time.Time, error) {
    var last *time.Time
    var enabled bool
    err := s.db.Exec(ctx).QueryRow(ctx,
        `SELECT count(*) > 0, max(last_used_at) FROM scim_tokens WHERE revoked_at IS NULL`).
        Scan(&enabled, &last)
    if err != nil {
        return false, nil, fmt.Errorf("scim token status: %w", err)
    }
    return enabled, last, nil
}

// --- groups ---

// InsertGroup creates a SCIM group resource.
func (s *Store) InsertGroup(ctx context.Context, g domain.Group) error {
    var ext any
    if g.ExternalID != "" {
        ext = g.ExternalID
    }
    if _, err := s.db.Exec(ctx).Exec(ctx,
        `INSERT INTO scim_groups (id, external_id, display_name) VALUES ($1, $2, $3)`,
        g.ID, ext, g.DisplayName); err != nil {
        return fmt.Errorf("scim insert group: %w", err)
    }
    return nil
}

// UpdateGroup replaces a group's display name (and external id when non-empty) and bumps updated_at.
func (s *Store) UpdateGroup(ctx context.Context, id, displayName, externalID string) error {
    var ext any
    if externalID != "" {
        ext = externalID
    }
    if _, err := s.db.Exec(ctx).Exec(ctx,
        `UPDATE scim_groups SET display_name = $2, external_id = COALESCE($3, external_id), updated_at = now() WHERE id = $1`,
        id, displayName, ext); err != nil {
        return fmt.Errorf("scim update group: %w", err)
    }
    return nil
}

func scanGroup(row interface{ Scan(...any) error }, g *domain.Group) error {
    var ext *string
    if err := row.Scan(&g.ID, &ext, &g.DisplayName, &g.CreatedAt, &g.UpdatedAt); err != nil {
        return err
    }
    if ext != nil {
        g.ExternalID = *ext
    }
    return nil
}

// GetGroup loads a group by id.
func (s *Store) GetGroup(ctx context.Context, id string) (domain.Group, bool, error) {
    var g domain.Group
    err := scanGroup(s.db.Exec(ctx).QueryRow(ctx,
        `SELECT id, external_id, display_name, created_at, updated_at FROM scim_groups WHERE id = $1`, id), &g)
    if errors.Is(err, pgx.ErrNoRows) {
        return domain.Group{}, false, nil
    }
    if err != nil {
        return domain.Group{}, false, fmt.Errorf("scim get group: %w", err)
    }
    return g, true, nil
}

// GroupByDisplayName loads the oldest group with a case-insensitive displayName match (filter).
func (s *Store) GroupByDisplayName(ctx context.Context, displayName string) (domain.Group, bool, error) {
    var g domain.Group
    err := scanGroup(s.db.Exec(ctx).QueryRow(ctx,
        `SELECT id, external_id, display_name, created_at, updated_at FROM scim_groups
          WHERE lower(display_name) = lower($1) ORDER BY created_at LIMIT 1`, displayName), &g)
    if errors.Is(err, pgx.ErrNoRows) {
        return domain.Group{}, false, nil
    }
    if err != nil {
        return domain.Group{}, false, fmt.Errorf("scim group by display name: %w", err)
    }
    return g, true, nil
}

// ListGroups returns a page of groups (ordered) plus the total count.
func (s *Store) ListGroups(ctx context.Context, offset, limit int) ([]domain.Group, int, error) {
    if limit <= 0 {
        limit = 100
    }
    if offset < 0 {
        offset = 0
    }
    var total int
    if err := s.db.Exec(ctx).QueryRow(ctx, `SELECT count(*) FROM scim_groups`).Scan(&total); err != nil {
        return nil, 0, fmt.Errorf("scim count groups: %w", err)
    }
    rows, err := s.db.Exec(ctx).Query(ctx,
        `SELECT id, external_id, display_name, created_at, updated_at FROM scim_groups
          ORDER BY created_at, id LIMIT $1 OFFSET $2`, limit, offset)
    if err != nil {
        return nil, 0, fmt.Errorf("scim list groups: %w", err)
    }
    defer rows.Close()
    var out []domain.Group
    for rows.Next() {
        var g domain.Group
        if err := scanGroup(rows, &g); err != nil {
            return nil, 0, fmt.Errorf("scim scan group: %w", err)
        }
        out = append(out, g)
    }
    return out, total, rows.Err()
}

// DeleteGroup removes a group (members/mappings/grants cascade via FK).
func (s *Store) DeleteGroup(ctx context.Context, id string) error {
    if _, err := s.db.Exec(ctx).Exec(ctx, `DELETE FROM scim_groups WHERE id = $1`, id); err != nil {
        return fmt.Errorf("scim delete group: %w", err)
    }
    return nil
}

// --- members ---

// ListMembers returns the user ids in a group.
func (s *Store) ListMembers(ctx context.Context, groupID string) ([]string, error) {
    rows, err := s.db.Exec(ctx).Query(ctx, `SELECT user_id FROM scim_group_members WHERE group_id = $1`, groupID)
    if err != nil {
        return nil, fmt.Errorf("scim list members: %w", err)
    }
    defer rows.Close()
    var out []string
    for rows.Next() {
        var uid string
        if err := rows.Scan(&uid); err != nil {
            return nil, fmt.Errorf("scim scan member: %w", err)
        }
        out = append(out, uid)
    }
    return out, rows.Err()
}

// AddMember adds a user to a group (idempotent).
func (s *Store) AddMember(ctx context.Context, groupID, userID string) error {
    if _, err := s.db.Exec(ctx).Exec(ctx,
        `INSERT INTO scim_group_members (group_id, user_id) VALUES ($1, $2) ON CONFLICT DO NOTHING`,
        groupID, userID); err != nil {
        return fmt.Errorf("scim add member: %w", err)
    }
    return nil
}

// RemoveMember removes a user from a group (no-op when absent).
func (s *Store) RemoveMember(ctx context.Context, groupID, userID string) error {
    if _, err := s.db.Exec(ctx).Exec(ctx,
        `DELETE FROM scim_group_members WHERE group_id = $1 AND user_id = $2`, groupID, userID); err != nil {
        return fmt.Errorf("scim remove member: %w", err)
    }
    return nil
}

// ReplaceMembers sets a group's membership to exactly userIDs (PUT). Runs in one tx.
func (s *Store) ReplaceMembers(ctx context.Context, groupID string, userIDs []string) error {
    return s.db.Do(ctx, func(ctx context.Context) error {
        ex := s.db.Exec(ctx)
        if _, err := ex.Exec(ctx, `DELETE FROM scim_group_members WHERE group_id = $1`, groupID); err != nil {
            return fmt.Errorf("scim replace members clear: %w", err)
        }
        for _, uid := range userIDs {
            if uid == "" {
                continue
            }
            if _, err := ex.Exec(ctx,
                `INSERT INTO scim_group_members (group_id, user_id) VALUES ($1, $2) ON CONFLICT DO NOTHING`,
                groupID, uid); err != nil {
                return fmt.Errorf("scim replace members insert: %w", err)
            }
        }
        return nil
    })
}

// GroupIDsForUser returns the scim group ids a user belongs to.
func (s *Store) GroupIDsForUser(ctx context.Context, userID string) ([]string, error) {
    rows, err := s.db.Exec(ctx).Query(ctx, `SELECT group_id FROM scim_group_members WHERE user_id = $1`, userID)
    if err != nil {
        return nil, fmt.Errorf("scim groups for user: %w", err)
    }
    defer rows.Close()
    var out []string
    for rows.Next() {
        var gid string
        if err := rows.Scan(&gid); err != nil {
            return nil, fmt.Errorf("scim scan group id: %w", err)
        }
        out = append(out, gid)
    }
    return out, rows.Err()
}

// --- admin mappings ---

// ListMappings returns every scim_group_id -> role_id mapping.
func (s *Store) ListMappings(ctx context.Context) ([]domain.GroupRoleMapping, error) {
    rows, err := s.db.Exec(ctx).Query(ctx, `SELECT scim_group_id, role_id FROM scim_group_roles`)
    if err != nil {
        return nil, fmt.Errorf("scim list mappings: %w", err)
    }
    defer rows.Close()
    var out []domain.GroupRoleMapping
    for rows.Next() {
        var m domain.GroupRoleMapping
        if err := rows.Scan(&m.ScimGroupID, &m.RoleID); err != nil {
            return nil, fmt.Errorf("scim scan mapping: %w", err)
        }
        out = append(out, m)
    }
    return out, rows.Err()
}

// UpsertMapping inserts or replaces a group -> role mapping.
func (s *Store) UpsertMapping(ctx context.Context, scimGroupID, roleID string) error {
    if _, err := s.db.Exec(ctx).Exec(ctx,
        `INSERT INTO scim_group_roles (scim_group_id, role_id) VALUES ($1, $2)
         ON CONFLICT (scim_group_id) DO UPDATE SET role_id = EXCLUDED.role_id`, scimGroupID, roleID); err != nil {
        return fmt.Errorf("scim upsert mapping: %w", err)
    }
    return nil
}

// DeleteMapping removes a mapping (no-op when absent).
func (s *Store) DeleteMapping(ctx context.Context, scimGroupID string) error {
    if _, err := s.db.Exec(ctx).Exec(ctx, `DELETE FROM scim_group_roles WHERE scim_group_id = $1`, scimGroupID); err != nil {
        return fmt.Errorf("scim delete mapping: %w", err)
    }
    return nil
}

// --- reconciliation ledger ---

// GrantsForUser returns a user's SCIM reconciliation-ledger rows.
func (s *Store) GrantsForUser(ctx context.Context, userID string) ([]domain.RoleGrant, error) {
    rows, err := s.db.Exec(ctx).Query(ctx, `SELECT role_id, scim_group_id FROM scim_role_grants WHERE user_id = $1`, userID)
    if err != nil {
        return nil, fmt.Errorf("scim grants for user: %w", err)
    }
    defer rows.Close()
    var out []domain.RoleGrant
    for rows.Next() {
        var g domain.RoleGrant
        if err := rows.Scan(&g.RoleID, &g.ScimGroupID); err != nil {
            return nil, fmt.Errorf("scim scan grant: %w", err)
        }
        out = append(out, g)
    }
    return out, rows.Err()
}

// InsertGrant records a reconciliation grant (idempotent on (user_id, role_id)).
func (s *Store) InsertGrant(ctx context.Context, userID, roleID, scimGroupID string) error {
    if _, err := s.db.Exec(ctx).Exec(ctx,
        `INSERT INTO scim_role_grants (user_id, role_id, scim_group_id) VALUES ($1, $2, $3)
         ON CONFLICT (user_id, role_id) DO UPDATE SET scim_group_id = EXCLUDED.scim_group_id`,
        userID, roleID, scimGroupID); err != nil {
        return fmt.Errorf("scim insert grant: %w", err)
    }
    return nil
}

// DeleteGrant removes a ledger row.
func (s *Store) DeleteGrant(ctx context.Context, userID, roleID string) error {
    if _, err := s.db.Exec(ctx).Exec(ctx, `DELETE FROM scim_role_grants WHERE user_id = $1 AND role_id = $2`, userID, roleID); err != nil {
        return fmt.Errorf("scim delete grant: %w", err)
    }
    return nil
}

// --- user reads (read-only cross-table reads) ---

// scimUserSelect is the users⋈scim-identity projection. LEFT JOIN so a user with no scim
// identity still returns (subject NULL -> ExternalID "").
const scimUserSelect = `SELECT u.id, u.email, u.display_name, u.disabled, i.subject
    FROM users u LEFT JOIN user_identities i ON i.user_id = u.id AND i.idp = 'scim'`

func scanScimUser(row interface{ Scan(...any) error }, u *app.ScimUser) error {
    var subject *string
    if err := row.Scan(&u.ID, &u.Email, &u.DisplayName, &u.Disabled, &subject); err != nil {
        return err
    }
    if subject != nil {
        u.ExternalID = *subject
    }
    return nil
}

// GetProvisionedUser returns a provider='scim' user by id.
func (s *Store) GetProvisionedUser(ctx context.Context, userID string) (app.ScimUser, bool, error) {
    var u app.ScimUser
    err := scanScimUser(s.db.Exec(ctx).QueryRow(ctx,
        scimUserSelect+` WHERE u.id = $1 AND u.provider = 'scim'`, userID), &u)
    if errors.Is(err, pgx.ErrNoRows) {
        return app.ScimUser{}, false, nil
    }
    if err != nil {
        return app.ScimUser{}, false, fmt.Errorf("scim get provisioned user: %w", err)
    }
    return u, true, nil
}

// UserByEmail returns the oldest provider='scim' user with this email.
func (s *Store) UserByEmail(ctx context.Context, email string) (app.ScimUser, bool, error) {
    var u app.ScimUser
    err := scanScimUser(s.db.Exec(ctx).QueryRow(ctx,
        scimUserSelect+` WHERE u.email = $1 AND u.provider = 'scim' ORDER BY u.created_at LIMIT 1`, email), &u)
    if errors.Is(err, pgx.ErrNoRows) {
        return app.ScimUser{}, false, nil
    }
    if err != nil {
        return app.ScimUser{}, false, fmt.Errorf("scim user by email: %w", err)
    }
    return u, true, nil
}

// UserByExternalID returns the user linked to (idp='scim', subject=externalID).
func (s *Store) UserByExternalID(ctx context.Context, externalID string) (app.ScimUser, bool, error) {
    var u app.ScimUser
    err := scanScimUser(s.db.Exec(ctx).QueryRow(ctx,
        scimUserSelect+` WHERE i.subject = $1 AND u.provider = 'scim'`, externalID), &u)
    if errors.Is(err, pgx.ErrNoRows) {
        return app.ScimUser{}, false, nil
    }
    if err != nil {
        return app.ScimUser{}, false, fmt.Errorf("scim user by external id: %w", err)
    }
    return u, true, nil
}

// ListProvisionedUsers returns a page of provider='scim' users + the total.
func (s *Store) ListProvisionedUsers(ctx context.Context, offset, limit int) ([]app.ScimUser, int, error) {
    if limit <= 0 {
        limit = 100
    }
    if offset < 0 {
        offset = 0
    }
    var total int
    if err := s.db.Exec(ctx).QueryRow(ctx, `SELECT count(*) FROM users WHERE provider = 'scim'`).Scan(&total); err != nil {
        return nil, 0, fmt.Errorf("scim count provisioned users: %w", err)
    }
    rows, err := s.db.Exec(ctx).Query(ctx,
        scimUserSelect+` WHERE u.provider = 'scim' ORDER BY u.created_at, u.id LIMIT $1 OFFSET $2`, limit, offset)
    if err != nil {
        return nil, 0, fmt.Errorf("scim list provisioned users: %w", err)
    }
    defer rows.Close()
    var out []app.ScimUser
    for rows.Next() {
        var u app.ScimUser
        if err := scanScimUser(rows, &u); err != nil {
            return nil, 0, fmt.Errorf("scim scan provisioned user: %w", err)
        }
        out = append(out, u)
    }
    return out, total, rows.Err()
}

// EmailExists reports whether ANY user (any provider) has this email.
func (s *Store) EmailExists(ctx context.Context, email string) (bool, error) {
    var exists bool
    if err := s.db.Exec(ctx).QueryRow(ctx, `SELECT EXISTS(SELECT 1 FROM users WHERE email = $1)`, email).Scan(&exists); err != nil {
        return false, fmt.Errorf("scim email exists: %w", err)
    }
    return exists, nil
}

// --- status ---

// ProvisionedUserCount counts SCIM-provisioned accounts (read-only cross-table read of `users`).
func (s *Store) ProvisionedUserCount(ctx context.Context) (int, error) {
    var n int
    if err := s.db.Exec(ctx).QueryRow(ctx, `SELECT count(*) FROM users WHERE provider = 'scim'`).Scan(&n); err != nil {
        return 0, fmt.Errorf("scim provisioned user count: %w", err)
    }
    return n, nil
}

var _ app.Store = (*Store)(nil)

git add go/migrations/00084_scim.sql go/migrations/00085_scim_group_roles.sql go/internal/scim/domain/scim.go go/internal/scim/app/ports.go go/internal/scim/adapters/pg.go
git commit -m "feat(scim): migrations 00084/00085 + scim domain, ports, Postgres store"

package app

import (
    "context"
    "crypto/rand"
    "crypto/sha256"
    "crypto/subtle"
    "encoding/base64"
    "encoding/hex"
    "fmt"
    "log/slog"
    "strings"
    "time"

    "github.com/Virtue-Digital-Indonesia/obscura/internal/kernel"
    "github.com/Virtue-Digital-Indonesia/obscura/internal/scim/domain"
)

// Service is the SCIM use-case layer: token lifecycle, user provisioning/deprovisioning, group
// resources, and group->role reconciliation. It writes accounts only through the UserPort (the
// audited auth paths) and role bindings only through the rbac RoleBinder.
type Service struct {
    store  Store
    users  UserPort
    binder RoleBinder
    logger *slog.Logger // optional; best-effort reconcile/touch logging
}

// NewService wires the SCIM service.
func NewService(store Store, users UserPort, binder RoleBinder, logger *slog.Logger) *Service {
    return &Service{store: store, users: users, binder: binder, logger: logger}
}

// scimErr is a kernel.Error the HTTP layer maps onto a SCIM error envelope (Kind -> status +
// scimType): ErrConflict->409 uniqueness, ErrValidation->400 invalidValue, ErrNotFound->404.
func scimErr(kind kernel.ErrorKind, code, msg string) error {
    return &kernel.Error{Kind: kind, Code: code, Message: msg}
}

// ---------------------------------------------------------------------------
// Tokens
// ---------------------------------------------------------------------------

// MintToken generates a fresh 32-byte token, revokes any prior active token (rotate), stores
// only sha256(token), and returns the RAW token ONCE. createdBy is the admin user id.
func (s *Service) MintToken(ctx context.Context, createdBy string) (string, error) {
    raw, err := randToken(32)
    if err != nil {
        return "", err
    }
    if err := s.store.RevokeActiveTokens(ctx); err != nil {
        return "", err
    }
    if err := s.store.InsertToken(ctx, kernel.NewID(), sha256hex(raw), createdBy); err != nil {
        return "", err
    }
    return raw, nil
}

// RevokeTokens revokes every active token (disables SCIM).
func (s *Service) RevokeTokens(ctx context.Context) error {
    return s.store.RevokeActiveTokens(ctx)
}

// VerifyToken reports whether the presented bearer token matches an active token, using a
// constant-time compare over sha256 hashes, and bumps last_used_at on a hit.
func (s *Service) VerifyToken(ctx context.Context, presented string) (bool, error) {
    if presented == "" {
        return false, nil
    }
    want := sha256hex(presented)
    hashes, err := s.store.ActiveTokenHashes(ctx)
    if err != nil {
        return false, err
    }
    match := false
    for _, h := range hashes {
        if subtle.ConstantTimeCompare([]byte(h), []byte(want)) == 1 {
            match = true
        }
    }
    if !match {
        return false, nil
    }
    if err := s.store.TouchToken(ctx, want); err != nil && s.logger != nil {
        s.logger.Warn("scim touch token failed", "err", err)
    }
    return true, nil
}

// Status reports whether SCIM is enabled (an active token exists), the last-used timestamp, and
// the count of provisioned users.
func (s *Service) Status(ctx context.Context) (enabled bool, lastUsedAt *time.Time, provisioned int, err error) {
    enabled, lastUsedAt, err = s.store.TokenStatus(ctx)
    if err != nil {
        return false, nil, 0, err
    }
    provisioned, err = s.store.ProvisionedUserCount(ctx)
    return enabled, lastUsedAt, provisioned, err
}

// ---------------------------------------------------------------------------
// User resources
// ---------------------------------------------------------------------------

// UserInput is the mapped input for creating/replacing a SCIM user (the HTTP layer decodes the
// SCIM JSON into this).
type UserInput struct {
    ExternalID  string
    UserName    string // maps to email
    Email       string // emails[primary].value; falls back to UserName
    DisplayName string
    Active      bool
}

// UserPatch is a set of optional attribute changes from a SCIM PATCH (nil = unchanged).
type UserPatch struct {
    Active      *bool
    DisplayName *string
    Email       *string
}

// GroupRef is a group a user belongs to (rendered in a User resource's groups).
type GroupRef struct {
    ID      string
    Display string
}

// UserResource is the SCIM-projected view the HTTP layer renders.
type UserResource struct {
    ID          string
    ExternalID  string
    UserName    string
    Email       string
    DisplayName string
    Active      bool
    Groups      []GroupRef
}

// CreateUser provisions a new SCIM user. Duplicate externalId, or ANY existing account with the
// same email, yields 409 uniqueness (SCIM must not collide with a local/oidc/ldap account).
func (s *Service) CreateUser(ctx context.Context, in UserInput) (UserResource, error) {
    email := strings.ToLower(strings.TrimSpace(firstNonEmpty(in.Email, in.UserName)))
    if email == "" {
        return UserResource{}, scimErr(kernel.ErrValidation, "scim.user.username_required", "userName or a primary email is required")
    }
    externalID := strings.TrimSpace(in.ExternalID)
    if externalID == "" {
        externalID = email // stable identity subject when the IdP omits externalId
    }
    if _, found, err := s.store.UserByExternalID(ctx, externalID); err != nil {
        return UserResource{}, err
    } else if found {
        return UserResource{}, scimErr(kernel.ErrConflict, "scim.user.duplicate", "a user with this externalId already exists")
    }
    if exists, err := s.store.EmailExists(ctx, email); err != nil {
        return UserResource{}, err
    } else if exists {
        return UserResource{}, scimErr(kernel.ErrConflict, "scim.user.duplicate", "a user with this userName already exists")
    }
    userID, err := s.users.Provision(ctx, externalID, email, in.DisplayName)
    if err != nil {
        return UserResource{}, err
    }
    if !in.Active {
        if err := s.applyActive(ctx, userID, false); err != nil {
            return UserResource{}, err
        }
    } else {
        s.reconcileBestEffort(ctx, userID, "create")
    }
    return s.userResource(ctx, userID)
}

// GetUserResource returns a provisioned user by id (404 when absent / not SCIM-managed).
func (s *Service) GetUserResource(ctx context.Context, id string) (UserResource, error) {
    return s.userResource(ctx, id)
}

// ListUsers implements GET /Users. attr is "" (enumerate), "userName", or "externalId"; val is
// the eq value. startIndex is 1-based; count is the page size (0 => metadata only).
func (s *Service) ListUsers(ctx context.Context, attr, val string, startIndex, count int) ([]UserResource, int, error) {
    switch attr {
    case "":
        offset := startIndex - 1
        if offset < 0 {
            offset = 0
        }
        users, total, err := s.store.ListProvisionedUsers(ctx, offset, count)
        if err != nil {
            return nil, 0, err
        }
        out := make([]UserResource, 0, len(users))
        for _, u := range users {
            out = append(out, s.projectUser(ctx, u))
        }
        return out, total, nil
    case "userName":
        u, found, err := s.store.UserByEmail(ctx, strings.ToLower(strings.TrimSpace(val)))
        if err != nil || !found {
            return nil, 0, err
        }
        return []UserResource{s.projectUser(ctx, u)}, 1, nil
    case "externalId":
        u, found, err := s.store.UserByExternalID(ctx, strings.TrimSpace(val))
        if err != nil || !found {
            return nil, 0, err
        }
        return []UserResource{s.projectUser(ctx, u)}, 1, nil
    default:
        return nil, 0, scimErr(kernel.ErrValidation, "scim.filter.unsupported", "unsupported filter attribute")
    }
}

// ReplaceUser implements PUT /Users/{id} (full replace of the mapped attributes + active).
func (s *Service) ReplaceUser(ctx context.Context, id string, in UserInput) (UserResource, error) {
    u, found, err := s.store.GetProvisionedUser(ctx, id)
    if err != nil {
        return UserResource{}, err
    }
    if !found {
        return UserResource{}, scimErr(kernel.ErrNotFound, "scim.user.not_found", "user not found")
    }
    email := strings.ToLower(strings.TrimSpace(firstNonEmpty(in.Email, in.UserName, u.Email)))
    dn := in.DisplayName
    if err := s.users.UpdateProfile(ctx, id, &dn, &email); err != nil {
        return UserResource{}, err
    }
    if err := s.applyActive(ctx, id, in.Active); err != nil {
        return UserResource{}, err
    }
    return s.userResource(ctx, id)
}

// PatchUser implements PATCH /Users/{id} (partial replace/add of active/displayName/email).
func (s *Service) PatchUser(ctx context.Context, id string, p UserPatch) (UserResource, error) {
    if _, found, err := s.store.GetProvisionedUser(ctx, id); err != nil {
        return UserResource{}, err
    } else if !found {
        return UserResource{}, scimErr(kernel.ErrNotFound, "scim.user.not_found", "user not found")
    }
    if p.DisplayName != nil || p.Email != nil {
        var emailPtr *string
        if p.Email != nil {
            e := strings.ToLower(strings.TrimSpace(*p.Email))
            emailPtr = &e
        }
        if err := s.users.UpdateProfile(ctx, id, p.DisplayName, emailPtr); err != nil {
            return UserResource{}, err
        }
    }
    if p.Active != nil {
        if err := s.applyActive(ctx, id, *p.Active); err != nil {
            return UserResource{}, err
        }
    }
    return s.userResource(ctx, id)
}

// DeleteUser implements DELETE /Users/{id} as a DEPROVISION (disable + revoke + strip grants) —
// never a hard delete, per the spec. A later GET returns the user with active=false.
func (s *Service) DeleteUser(ctx context.Context, id string) error {
    if _, found, err := s.store.GetProvisionedUser(ctx, id); err != nil {
        return err
    } else if !found {
        return scimErr(kernel.ErrNotFound, "scim.user.not_found", "user not found")
    }
    return s.applyActive(ctx, id, false)
}

// applyActive enables or DEPROVISIONS a user and re-reconciles their SCIM roles. Disable also
// revokes live sessions; reconcile then strips every SCIM grant (a disabled user's desired set
// is empty). Enable re-reconciles from current membership. Idempotent.
func (s *Service) applyActive(ctx context.Context, userID string, active bool) error {
    if active {
        if err := s.users.SetDisabled(ctx, userID, false); err != nil {
            return err
        }
    } else {
        if err := s.users.SetDisabled(ctx, userID, true); err != nil {
            return err
        }
        if err := s.users.RevokeSessions(ctx, userID); err != nil {
            return err
        }
    }
    return s.reconcileUser(ctx, userID)
}

func (s *Service) userResource(ctx context.Context, userID string) (UserResource, error) {
    u, found, err := s.store.GetProvisionedUser(ctx, userID)
    if err != nil {
        return UserResource{}, err
    }
    if !found {
        return UserResource{}, scimErr(kernel.ErrNotFound, "scim.user.not_found", "user not found")
    }
    return s.projectUser(ctx, u), nil
}

func (s *Service) projectUser(ctx context.Context, u ScimUser) UserResource {
    res := UserResource{
        ID: u.ID, ExternalID: u.ExternalID, UserName: u.Email, Email: u.Email,
        DisplayName: u.DisplayName, Active: !u.Disabled,
    }
    if gids, err := s.store.GroupIDsForUser(ctx, u.ID); err == nil {
        for _, gid := range gids {
            if g, ok, gerr := s.store.GetGroup(ctx, gid); gerr == nil && ok {
                res.Groups = append(res.Groups, GroupRef{ID: g.ID, Display: g.DisplayName})
            }
        }
    }
    return res
}

// ---------------------------------------------------------------------------
// Group resources
// ---------------------------------------------------------------------------

// GroupInput is the mapped input for creating/replacing a SCIM group. MemberUserIDs are the SCIM
// members[].value entries (each an Obscura user id).
type GroupInput struct {
    ExternalID    string
    DisplayName   string
    MemberUserIDs []string
}

// GroupPatch is a set of optional group changes from a SCIM PATCH.
type GroupPatch struct {
    DisplayName    *string
    AddMembers     []string
    RemoveMembers  []string
    ReplaceMembers *[]string // non-nil => set membership to exactly this set
}

// GroupMember is one rendered member (value = user id, display = email).
type GroupMember struct {
    UserID  string
    Display string
}

// GroupResource is the SCIM-projected view the HTTP layer renders.
type GroupResource struct {
    ID          string
    ExternalID  string
    DisplayName string
    Members     []GroupMember
}

// CreateGroup provisions a new SCIM group. Duplicate displayName -> 409 uniqueness.
func (s *Service) CreateGroup(ctx context.Context, in GroupInput) (GroupResource, error) {
    dn := strings.TrimSpace(in.DisplayName)
    if dn == "" {
        return GroupResource{}, scimErr(kernel.ErrValidation, "scim.group.display_required", "displayName is required")
    }
    if _, found, err := s.store.GroupByDisplayName(ctx, dn); err != nil {
        return GroupResource{}, err
    } else if found {
        return GroupResource{}, scimErr(kernel.ErrConflict, "scim.group.duplicate", "a group with this displayName already exists")
    }
    g := domain.Group{ID: kernel.NewID(), ExternalID: strings.TrimSpace(in.ExternalID), DisplayName: dn}
    if err := s.store.InsertGroup(ctx, g); err != nil {
        return GroupResource{}, err
    }
    if len(in.MemberUserIDs) > 0 {
        if err := s.store.ReplaceMembers(ctx, g.ID, in.MemberUserIDs); err != nil {
            return GroupResource{}, err
        }
        s.reconcileMembersBestEffort(ctx, in.MemberUserIDs, "group create")
    }
    return s.groupResource(ctx, g.ID)
}

// GetGroupResource returns a group by id (404 when absent).
func (s *Service) GetGroupResource(ctx context.Context, id string) (GroupResource, error) {
    return s.groupResource(ctx, id)
}

// ListGroups implements GET /Groups. attr is "" (enumerate) or "displayName"; val is the eq value.
func (s *Service) ListGroups(ctx context.Context, attr, val string, startIndex, count int) ([]GroupResource, int, error) {
    switch attr {
    case "":
        offset := startIndex - 1
        if offset < 0 {
            offset = 0
        }
        groups, total, err := s.store.ListGroups(ctx, offset, count)
        if err != nil {
            return nil, 0, err
        }
        out := make([]GroupResource, 0, len(groups))
        for _, g := range groups {
            r, rerr := s.groupResource(ctx, g.ID)
            if rerr != nil {
                return nil, 0, rerr
            }
            out = append(out, r)
        }
        return out, total, nil
    case "displayName":
        g, found, err := s.store.GroupByDisplayName(ctx, strings.TrimSpace(val))
        if err != nil || !found {
            return nil, 0, err
        }
        r, rerr := s.groupResource(ctx, g.ID)
        if rerr != nil {
            return nil, 0, rerr
        }
        return []GroupResource{r}, 1, nil
    default:
        return nil, 0, scimErr(kernel.ErrValidation, "scim.filter.unsupported", "unsupported filter attribute")
    }
}

// ReplaceGroup implements PUT /Groups/{id} (displayName + full membership replace).
func (s *Service) ReplaceGroup(ctx context.Context, id string, in GroupInput) (GroupResource, error) {
    if _, found, err := s.store.GetGroup(ctx, id); err != nil {
        return GroupResource{}, err
    } else if !found {
        return GroupResource{}, scimErr(kernel.ErrNotFound, "scim.group.not_found", "group not found")
    }
    if dn := strings.TrimSpace(in.DisplayName); dn != "" {
        if err := s.store.UpdateGroup(ctx, id, dn, strings.TrimSpace(in.ExternalID)); err != nil {
            return GroupResource{}, err
        }
    }
    before, err := s.store.ListMembers(ctx, id)
    if err != nil {
        return GroupResource{}, err
    }
    if err := s.store.ReplaceMembers(ctx, id, in.MemberUserIDs); err != nil {
        return GroupResource{}, err
    }
    s.reconcileMembersBestEffort(ctx, union(before, in.MemberUserIDs), "group replace")
    return s.groupResource(ctx, id)
}

// PatchGroup implements PATCH /Groups/{id} (displayName replace and/or member add/remove/replace).
func (s *Service) PatchGroup(ctx context.Context, id string, p GroupPatch) (GroupResource, error) {
    g, found, err := s.store.GetGroup(ctx, id)
    if err != nil {
        return GroupResource{}, err
    }
    if !found {
        return GroupResource{}, scimErr(kernel.ErrNotFound, "scim.group.not_found", "group not found")
    }
    if p.DisplayName != nil {
        if err := s.store.UpdateGroup(ctx, id, strings.TrimSpace(*p.DisplayName), g.ExternalID); err != nil {
            return GroupResource{}, err
        }
    }
    var affected []string
    if p.ReplaceMembers != nil {
        before, err := s.store.ListMembers(ctx, id)
        if err != nil {
            return GroupResource{}, err
        }
        if err := s.store.ReplaceMembers(ctx, id, *p.ReplaceMembers); err != nil {
            return GroupResource{}, err
        }
        affected = union(before, *p.ReplaceMembers)
    } else {
        for _, uid := range p.AddMembers {
            if err := s.store.AddMember(ctx, id, uid); err != nil {
                return GroupResource{}, err
            }
        }
        for _, uid := range p.RemoveMembers {
            if err := s.store.RemoveMember(ctx, id, uid); err != nil {
                return GroupResource{}, err
            }
        }
        affected = union(p.AddMembers, p.RemoveMembers)
    }
    s.reconcileMembersBestEffort(ctx, affected, "group patch")
    return s.groupResource(ctx, id)
}

// DeleteGroup removes a group. To avoid orphaning rbac bindings (the ledger cascades on the
// scim_group_id FK, which would bypass the binder), the mapping is deleted and every member
// reconciled FIRST (revoking their group-derived roles via the binder + ledger), THEN the group
// row is dropped.
func (s *Service) DeleteGroup(ctx context.Context, id string) error {
    if _, found, err := s.store.GetGroup(ctx, id); err != nil {
        return err
    } else if !found {
        return scimErr(kernel.ErrNotFound, "scim.group.not_found", "group not found")
    }
    members, err := s.store.ListMembers(ctx, id)
    if err != nil {
        return err
    }
    if err := s.store.DeleteMapping(ctx, id); err != nil {
        return err
    }
    s.reconcileMembersBestEffort(ctx, members, "group delete")
    return s.store.DeleteGroup(ctx, id)
}

func (s *Service) groupResource(ctx context.Context, id string) (GroupResource, error) {
    g, found, err := s.store.GetGroup(ctx, id)
    if err != nil {
        return GroupResource{}, err
    }
    if !found {
        return GroupResource{}, scimErr(kernel.ErrNotFound, "scim.group.not_found", "group not found")
    }
    res := GroupResource{ID: g.ID, ExternalID: g.ExternalID, DisplayName: g.DisplayName}
    if uids, merr := s.store.ListMembers(ctx, id); merr == nil {
        for _, uid := range uids {
            display := uid
            if u, ok, uerr := s.store.GetProvisionedUser(ctx, uid); uerr == nil && ok {
                display = u.Email
            }
            res.Members = append(res.Members, GroupMember{UserID: uid, Display: display})
        }
    }
    return res, nil
}

// ---------------------------------------------------------------------------
// Admin mapping surface (session-authed handlers call these)
// ---------------------------------------------------------------------------

// ListGroupsRaw returns a page of groups (id + displayName) for the admin mapping dropdown.
func (s *Service) ListGroupsRaw(ctx context.Context, offset, limit int) ([]domain.Group, int, error) {
    return s.store.ListGroups(ctx, offset, limit)
}

// ListGroupRoleMappings returns the admin-managed group->role mappings.
func (s *Service) ListGroupRoleMappings(ctx context.Context) ([]domain.GroupRoleMapping, error) {
    return s.store.ListMappings(ctx)
}

// SetGroupRoleMapping upserts a mapping and re-reconciles every member of the group.
func (s *Service) SetGroupRoleMapping(ctx context.Context, scimGroupID, roleID string) error {
    if strings.TrimSpace(scimGroupID) == "" {
        return scimErr(kernel.ErrValidation, "scim.mapping.group_required", "scim group id is required")
    }
    if strings.TrimSpace(roleID) == "" {
        return scimErr(kernel.ErrValidation, "scim.mapping.role_required", "role id is required")
    }
    if _, found, err := s.store.GetGroup(ctx, scimGroupID); err != nil {
        return err
    } else if !found {
        return scimErr(kernel.ErrNotFound, "scim.group.not_found", "scim group not found")
    }
    if err := s.store.UpsertMapping(ctx, scimGroupID, roleID); err != nil {
        return err
    }
    s.reconcileGroupMembers(ctx, scimGroupID)
    return nil
}

// DeleteGroupRoleMapping removes a mapping and re-reconciles every member of the group.
func (s *Service) DeleteGroupRoleMapping(ctx context.Context, scimGroupID string) error {
    if strings.TrimSpace(scimGroupID) == "" {
        return scimErr(kernel.ErrValidation, "scim.mapping.group_required", "scim group id is required")
    }
    if err := s.store.DeleteMapping(ctx, scimGroupID); err != nil {
        return err
    }
    s.reconcileGroupMembers(ctx, scimGroupID)
    return nil
}

// ---------------------------------------------------------------------------
// Reconciliation
// ---------------------------------------------------------------------------

// reconcileUser brings a user's scim_role_grants in line with (their current SCIM group
// membership × the admin mappings). A disabled user's desired set is empty (all SCIM grants
// stripped). Manual bindings (no ledger row) are never touched. RefreshEffectivePerms once on
// change. Parallels the LDAP reconciler.
func (s *Service) reconcileUser(ctx context.Context, userID string) error {
    desired := map[string]string{} // roleID -> scimGroupID
    if u, found, err := s.store.GetProvisionedUser(ctx, userID); err != nil {
        return err
    } else if found && !u.Disabled {
        gids, err := s.store.GroupIDsForUser(ctx, userID)
        if err != nil {
            return err
        }
        if len(gids) > 0 {
            mappings, err := s.store.ListMappings(ctx)
            if err != nil {
                return err
            }
            byGroup := make(map[string]string, len(mappings))
            for _, m := range mappings {
                byGroup[m.ScimGroupID] = m.RoleID
            }
            for _, gid := range gids {
                if rid, ok := byGroup[gid]; ok {
                    desired[rid] = gid
                }
            }
        }
    }
    current, err := s.store.GrantsForUser(ctx, userID)
    if err != nil {
        return err
    }
    have := make(map[string]bool, len(current))
    changed := false
    for _, g := range current {
        have[g.RoleID] = true
        if _, keep := desired[g.RoleID]; !keep {
            if err := s.binder.UnbindRole(ctx, g.RoleID, subjectKindUser, userID); err != nil {
                return err
            }
            if err := s.store.DeleteGrant(ctx, userID, g.RoleID); err != nil {
                return err
            }
            changed = true
        }
    }
    for rid, gid := range desired {
        if have[rid] {
            continue
        }
        if err := s.binder.BindRole(ctx, rid, subjectKindUser, userID); err != nil {
            return err
        }
        if err := s.store.InsertGrant(ctx, userID, rid, gid); err != nil {
            return err
        }
        changed = true
    }
    if changed {
        return s.binder.RefreshEffectivePerms(ctx)
    }
    return nil
}

func (s *Service) reconcileGroupMembers(ctx context.Context, groupID string) {
    members, err := s.store.ListMembers(ctx, groupID)
    if err != nil {
        if s.logger != nil {
            s.logger.Warn("scim list members for reconcile failed", "group", groupID, "err", err)
        }
        return
    }
    s.reconcileMembersBestEffort(ctx, members, "mapping change")
}

func (s *Service) reconcileMembersBestEffort(ctx context.Context, userIDs []string, reason string) {
    for _, uid := range userIDs {
        if uid == "" {
            continue
        }
        s.reconcileBestEffort(ctx, uid, reason)
    }
}

func (s *Service) reconcileBestEffort(ctx context.Context, userID, reason string) {
    if err := s.reconcileUser(ctx, userID); err != nil && s.logger != nil {
        s.logger.Warn("scim reconcile failed", "user", userID, "reason", reason, "err", err)
    }
}

// ---------------------------------------------------------------------------
// helpers (stdlib only)
// ---------------------------------------------------------------------------

func randToken(nbytes int) (string, error) {
    b := make([]byte, nbytes)
    if _, err := rand.Read(b); err != nil {
        return "", fmt.Errorf("scim rand: %w", err)
    }
    return base64.RawURLEncoding.EncodeToString(b), nil
}

func sha256hex(s string) string {
    sum := sha256.Sum256([]byte(s))
    return hex.EncodeToString(sum[:])
}

func firstNonEmpty(vals ...string) string {
    for _, v := range vals {
        if strings.TrimSpace(v) != "" {
            return v
        }
    }
    return ""
}

// union returns the de-duplicated concatenation of two id slices (for reconcile-affected sets).
func union(a, b []string) []string {
    seen := map[string]bool{}
    out := make([]string, 0, len(a)+len(b))
    for _, s := range append(append([]string{}, a...), b...) {
        if s == "" || seen[s] {
            continue
        }
        seen[s] = true
        out = append(out, s)
    }
    return out
}