@jini-ai/user-management 0.2.0

package/dist/react/users/hooks/use-users.hooks.js

@@ -0,0 +1,286 @@
+import { interpolate } from "@jini-ai/ui/panel-kit";
+import { useEffect, useRef, useState } from "react";
+import {} from "../../models.js";
+import { useFetchMutation, useFetchQuery } from "@jini-ai/ui/panel-kit";
+import { useAsyncAction } from "@jini-ai/ui/panel-kit";
+import { describeApiError as describeFeatureError, KEYS } from "../rules.js";
+async function runGrantMutation(generationAtStart, toggleGenerationRef, mutate, onSuccess, setGrantSaving, setGrantError, describeError) {
+    setGrantSaving(true);
+    setGrantError(null);
+    try {
+        await mutate();
+        if (toggleGenerationRef.current === generationAtStart)
+            onSuccess();
+    }
+    catch (e) {
+        if (toggleGenerationRef.current === generationAtStart)
+            setGrantError(describeError(e));
+    }
+    finally {
+        if (toggleGenerationRef.current === generationAtStart)
+            setGrantSaving(false);
+    }
+}
+export function useUsers({ port, translate, queryScope }, { openOwnPasswordReset = false, onOwnPasswordResetClosed } = {}) {
+    const describeApiError = (error, fallback) => describeFeatureError({ error, fallback, translate });
+    const t = translate;
+    const boundT = translate;
+    const portRef = useRef(port);
+    const list = useFetchQuery({
+        key: [queryScope, ...KEYS.list],
+        fetch: async () => {
+            const [u, r, p] = await Promise.all([port.listUsers({}), port.listRoles({}), port.listPolicies({})]);
+            return { users: u.users, roles: r.roles, policies: p.policies };
+        },
+    });
+    const users = list.data?.users ?? null;
+    const roles = list.data?.roles ?? null;
+    const policies = list.data?.policies ?? null;
+    const error = list.error ? describeApiError(list.error, t("failed to load users")) : null;
+    const [formOpen, setFormOpen] = useState(false);
+    const [username, setUsername] = useState("");
+    const [email, setEmail] = useState("");
+    const [password, setPassword] = useState("");
+    const createUser = useAsyncAction();
+    const createUserMutation = useFetchMutation({
+        run: ({ input }) => port.createUser({ username: input.username, password: input.password }, { email: input.email })
+    }, {
+        invalidates: [[queryScope, ...KEYS.list]],
+    });
+    const [expandedId, setExpandedId] = useState(null);
+    const toggleGenerationRef = useRef(0);
+    const [pendingRoleId, setPendingRoleId] = useState("");
+    const [pendingPolicyId, setPendingPolicyId] = useState("");
+    const [grantSaving, setGrantSaving] = useState(false);
+    const [grantError, setGrantError] = useState(null);
+    const assignRoleMutation = useFetchMutation({
+        run: ({ input }) => port.assignRole(input)
+    }, {
+        invalidates: [[queryScope, ...KEYS.list]],
+    });
+    const attachPolicyMutation = useFetchMutation({
+        run: ({ input }) => port.attachPolicy(input)
+    }, {
+        invalidates: [[queryScope, ...KEYS.list]],
+    });
+    const [editEmail, setEditEmail] = useState("");
+    const updateEmailMutation = useFetchMutation({
+        run: ({ input }) => port.updateUser({ principalId: input.principalId }, { email: input.email })
+    }, {
+        invalidates: [[queryScope, ...KEYS.list]],
+    });
+    const [toggleSavingId, setToggleSavingId] = useState(null);
+    const [toggleError, setToggleError] = useState(null);
+    const [notice, setNotice] = useState(null);
+    const toggleStatusMutation = useFetchMutation({
+        run: ({ input: user }) => (user.status === "active" ? port.disableUser({ principalId: user.principalId }) : port.enableUser({ principalId: user.principalId }))
+    }, {
+        invalidates: [[queryScope, ...KEYS.list]],
+    });
+    const [confirmingDisable, setConfirmingDisable] = useState(null);
+    const [resetPasswordFor, setResetPasswordFor] = useState(null);
+    const [newPassword, setNewPassword] = useState("");
+    const resetPassword = useAsyncAction();
+    const [ownPrincipalId, setOwnPrincipalId] = useState(null);
+    const [canManageUserTrash, setCanManageUserTrash] = useState(false);
+    useEffect(() => {
+        let cancelled = false;
+        portRef.current
+            .me({})
+            .then((res) => {
+            if (!cancelled) {
+                setOwnPrincipalId(res.user.id);
+                setCanManageUserTrash(res.canManageUserTrash);
+            }
+        })
+            .catch(() => {
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+    const deepLinkAttemptedRef = useRef(false);
+    const openedViaDeepLinkRef = useRef(false);
+    useEffect(() => {
+        if (!openOwnPasswordReset || deepLinkAttemptedRef.current)
+            return;
+        if (!users || ownPrincipalId === null)
+            return;
+        const ownRow = users.find((u) => u.principalId === ownPrincipalId);
+        if (!ownRow)
+            return;
+        deepLinkAttemptedRef.current = true;
+        openedViaDeepLinkRef.current = true;
+        openResetPassword(ownRow);
+    }, [openOwnPasswordReset, users, ownPrincipalId]);
+    useEffect(() => {
+        if (resetPasswordFor !== null || !openedViaDeepLinkRef.current)
+            return;
+        openedViaDeepLinkRef.current = false;
+        onOwnPasswordResetClosed?.();
+    }, [resetPasswordFor, onOwnPasswordResetClosed]);
+    const resetPasswordMutation = useFetchMutation({
+        run: ({ input }) => port.resetUserPassword(input),
+    });
+    async function onCreate(e) {
+        e.preventDefault();
+        await createUser.run({ action: async () => {
+                await createUserMutation.mutate({ input: { username, password, email: email || undefined } });
+                setUsername("");
+                setEmail("");
+                setPassword("");
+                setFormOpen(false);
+            }, describeError: (e) => describeApiError(e, t("failed to create user")) });
+    }
+    function toggleExpanded(user) {
+        setGrantError(null);
+        setGrantSaving(false);
+        setPendingRoleId("");
+        setPendingPolicyId("");
+        setEditEmail(user.email ?? "");
+        toggleGenerationRef.current += 1;
+        setExpandedId((current) => (current === user.principalId ? null : user.principalId));
+    }
+    async function onAssignRole({ principalId }) {
+        if (!pendingRoleId)
+            return;
+        await runGrantMutation(toggleGenerationRef.current, toggleGenerationRef, () => assignRoleMutation.mutate({ input: { principalId, roleId: pendingRoleId } }), () => setPendingRoleId(""), setGrantSaving, setGrantError, (e) => describeApiError(e, t("failed to assign role")));
+    }
+    async function onAttachPolicy({ principalId }) {
+        if (!pendingPolicyId)
+            return;
+        await runGrantMutation(toggleGenerationRef.current, toggleGenerationRef, () => attachPolicyMutation.mutate({ input: { principalId, policyId: pendingPolicyId } }), () => setPendingPolicyId(""), setGrantSaving, setGrantError, (e) => describeApiError(e, t("failed to attach policy")));
+    }
+    async function onSaveEmail({ principalId }) {
+        setGrantError(null);
+        try {
+            await updateEmailMutation.mutate({ input: { principalId, email: editEmail } });
+        }
+        catch (e) {
+            setGrantError(describeApiError(e, t("failed to update email")));
+        }
+    }
+    const emailSaving = updateEmailMutation.status === "pending";
+    function openResetPassword(user) {
+        if (toggleSavingId || resetPassword.saving)
+            return;
+        resetPassword.setError(null);
+        setNewPassword("");
+        setResetPasswordFor(user);
+    }
+    async function confirmResetPassword() {
+        if (!resetPasswordFor || !newPassword)
+            return;
+        await resetPassword.run({ action: async () => {
+                await resetPasswordMutation.mutate({ input: { principalId: resetPasswordFor.principalId, password: newPassword } });
+                setNotice(resetPasswordFor.principalId === ownPrincipalId
+                    ? t("Password changed. Sign in again with your new password.")
+                    : interpolate({ template: t('Password reset for "{username}" — every active session for this user was revoked.'), vars: { username: resetPasswordFor.username } }));
+                setResetPasswordFor(null);
+                setNewPassword("");
+            }, describeError: (e) => describeApiError(e, t("failed to reset password")) });
+    }
+    async function onToggleStatus(user) {
+        setToggleSavingId(user.principalId);
+        setToggleError(null);
+        try {
+            await toggleStatusMutation.mutate({ input: user });
+        }
+        catch (e) {
+            setToggleError(describeApiError(e, t("failed to change status")));
+        }
+        finally {
+            setToggleSavingId((current) => (current === user.principalId ? null : current));
+        }
+    }
+    function requestDisable(user) {
+        setToggleError(null);
+        setConfirmingDisable(user);
+    }
+    async function confirmDisable() {
+        if (!confirmingDisable)
+            return;
+        const user = confirmingDisable;
+        await onToggleStatus(user);
+        setConfirmingDisable((current) => (current?.principalId === user.principalId ? null : current));
+    }
+    const deleteUserMutation = useFetchMutation({
+        run: ({ input: principalId }) => port.deleteUser({ principalId: principalId })
+    }, {
+        invalidates: [[queryScope, ...KEYS.list]],
+    });
+    const [confirmingDelete, setConfirmingDelete] = useState(null);
+    function requestDelete(user) {
+        setToggleError(null);
+        setConfirmingDelete(user);
+    }
+    async function confirmDelete() {
+        if (!confirmingDelete)
+            return;
+        const user = confirmingDelete;
+        try {
+            await deleteUserMutation.mutate({ input: user.principalId });
+        }
+        catch (e) {
+            setToggleError(describeApiError(e, t("failed to delete user")));
+        }
+        setConfirmingDelete((current) => (current?.principalId === user.principalId ? null : current));
+    }
+    return {
+        users,
+        roles,
+        policies,
+        error,
+        formOpen,
+        setFormOpen,
+        username,
+        setUsername,
+        email,
+        setEmail,
+        password,
+        setPassword,
+        saving: createUser.saving,
+        formError: createUser.error,
+        onCreate,
+        expandedId,
+        toggleExpanded,
+        pendingRoleId,
+        setPendingRoleId,
+        pendingPolicyId,
+        setPendingPolicyId,
+        grantSaving,
+        grantError,
+        onAssignRole,
+        onAttachPolicy,
+        editEmail,
+        setEditEmail,
+        emailSaving,
+        onSaveEmail,
+        toggleSavingId,
+        toggleError,
+        notice,
+        confirmingDisable,
+        setConfirmingDisable,
+        requestDisable,
+        confirmDisable,
+        onToggleStatus,
+        resetPasswordFor,
+        setResetPasswordFor,
+        newPassword,
+        setNewPassword,
+        passwordSaving: resetPassword.saving,
+        passwordError: resetPassword.error,
+        setPasswordError: resetPassword.setError,
+        openResetPassword,
+        confirmResetPassword,
+        canManageUserTrash,
+        confirmingDelete,
+        setConfirmingDelete,
+        requestDelete,
+        deleteSaving: deleteUserMutation.status === "pending",
+        confirmDelete,
+        t: boundT,
+        translate,
+    };
+}
+//# sourceMappingURL=use-users.hooks.js.map

package/dist/react/users/rules.d.ts

@@ -0,0 +1,33 @@
+import type { AdminIdentityUser } from "../models.js";
+import type { Translate } from "@jini-ai/ui/panel-kit";
+import type { RowMenuItem } from "@jini-ai/admin/react";
+import type { QueryKey } from "@jini-ai/ui/panel-kit";
+export declare const KEYS: {
+    list: QueryKey;
+};
+export declare function describeApiError({ error, fallback, translate }: {
+    error: unknown;
+    fallback: string;
+    translate: Translate;
+}): string;
+export interface UserRowMenuHandlers {
+    onRequestDisable: (user: AdminIdentityUser) => void;
+    onEnable: (user: AdminIdentityUser) => void;
+    onManage: (user: AdminIdentityUser) => void;
+    onResetPassword: (user: AdminIdentityUser) => void;
+    onRequestDelete: (user: AdminIdentityUser) => void;
+}
+export declare function userRowMenuItems({ user, toggleSaving, handlers, translate, canDelete }: {
+    user: AdminIdentityUser;
+    toggleSaving: boolean;
+    handlers: UserRowMenuHandlers;
+    translate: Translate;
+    canDelete: boolean;
+}): RowMenuItem[];
+export declare function formatGrantLabel({ ids, byId }: {
+    ids: readonly string[];
+    byId: ReadonlyMap<string, {
+        name: string;
+    }>;
+}): string | null;
+//# sourceMappingURL=rules.d.ts.map

package/dist/react/users/rules.js

@@ -0,0 +1,61 @@
+import { describeIdentityError } from "../errors.js";
+export const KEYS = {
+    list: ["users-roles-policies"],
+};
+const STATIC_ERROR_MESSAGES = {
+    GRANT_EXCEEDS_ISSUER: "You cannot grant a permission you do not hold.",
+    FORBIDDEN: "You do not have permission to do that.",
+    RESOURCE_CONFLICT: "That username is already in use.",
+    OWNER_REQUIRED: "The workspace must keep at least one active owner.",
+    SELF_DELETE: "You cannot delete your own account.",
+    USER_IN_TRASH: "This user is in the Trash; restore them first.",
+    USERNAME_IN_TRASH: "A user with this username is in the Trash; restore or delete them permanently first.",
+};
+export function describeApiError({ error, fallback, translate }) {
+    return describeIdentityError({ error, fallback, translate }, { messages: STATIC_ERROR_MESSAGES });
+}
+export function userRowMenuItems({ user, toggleSaving, handlers, translate, canDelete }) {
+    const items = [
+        {
+            key: "toggle",
+            label: user.status === "active" ? translate("Disable") : translate("Enable"),
+            tone: user.status === "active" ? "warning" : "default",
+            onSelect: () => {
+                if (toggleSaving)
+                    return;
+                if (user.status === "active") {
+                    handlers.onRequestDisable(user);
+                }
+                else {
+                    handlers.onEnable(user);
+                }
+            },
+        },
+        {
+            key: "manage",
+            label: translate("Manage"),
+            onSelect: () => handlers.onManage(user),
+        },
+        {
+            key: "reset-password",
+            label: translate("Reset password"),
+            tone: "warning",
+            onSelect: () => handlers.onResetPassword(user),
+        },
+    ];
+    if (canDelete) {
+        items.push({
+            key: "delete",
+            label: translate("Delete"),
+            tone: "danger",
+            onSelect: () => handlers.onRequestDelete(user),
+        });
+    }
+    return items;
+}
+export function formatGrantLabel({ ids, byId }) {
+    if (ids.length === 0)
+        return null;
+    return ids.map((id) => byId.get(id)?.name ?? id).join(", ");
+}
+//# sourceMappingURL=rules.js.map

package/dist/server/admin-crud-service.d.ts

@@ -0,0 +1,295 @@
+import type { UUID } from "@jini-ai/core/primitives";
+import type { AuthServiceDeps } from "./auth-service.js";
+import { type PolicyPermissionRecord, type PolicyRecord, type PrincipalRecord, type RoleRecord, type UserRecord } from "../core/types.js";
+/**
+ * @file An amendment that completes the users/roles/policies admin CRUD surface
+ * (feature.spec.md..19).
+ *
+ * Purpose:
+ * Two of these nine transitions (`disablePrincipal`, `writePolicyPermission`) were fully specified
+ * since v0.5.0/v0.5.3 but never implemented — this file is their first implementation, not a
+ * re-specification. The other seven (`enablePrincipal`, `updateUser`,
+ * `resetUserPassword`, `updateRole`, `updatePolicy`, `deleteRole`, `deletePolicy`) are new
+ * transitions this amendment adds. Grouped in one file, separate from `grant-service.ts`'s
+ * "human grant-writing transitions" (`CREATE_*`/`ASSIGN_ROLE`/`ATTACH_POLICY`) because most of
+ * these are plain CRUD, not grant-writing — `writePolicyPermission` is the one exception (it IS
+ * -clamped) and reuses `grant-service.ts`'s exported `assertGrantClamp` rather than
+ * duplicating it.
+ *
+ * Architectural role:
+ * Ordinary core functions — same shape as `grant-service.ts`: one exported async
+ * function per transition, plain `Error` subclasses for control flow, the caller-permission gate
+ * enforced here (not pushed to the route layer).
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+/**
+ * `DISABLE_PRINCIPAL` (feature.spec.md, state.spec §3). Gated by
+ * `user.manage`. Refuses the seeded owner unconditionally ( CLI/core resolution target —
+ * disabling it would strand the CLI-only management plane) and refuses any disable that would drop
+ * the workspace's active owner-`*` count to zero — both checked, and the status update
+ * performed inside one identity transaction. Asynchronous repository calls yield even in a
+ * single-event-loop composition, so the transaction port must serialize competing owner/status
+ * writes for the whole workspace rather than rely on "atomic by construction" reasoning.
+ *
+ * `input.seededOwnerPrincipalId` is the caller's job to resolve (`await deps.ownerPrincipalId` at
+ * the route layer, mirroring `identityReady`'s existing await-before-use convention) — this
+ * function takes the already-resolved id so it stays a plain, directly-testable function.
+ *
+ * @complexity O(n) in the workspace's principal count (one `list` call to count active owner-`*`
+ * holders) — bounded by the same operator-managed-roster assumption `identity/INFO.md` already
+ * makes for `PrincipalRepoPort.list`.
+ * @overallScore 100
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function disablePrincipal(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        principalId: UUID;
+        seededOwnerPrincipalId: UUID;
+    };
+}): Promise<{
+    principal: PrincipalRecord;
+}>;
+/**
+ * `ENABLE_PRINCIPAL` (feature.spec.md ). Gated by `user.manage`. Target must be
+ * `kind='user'` — a `system`/`api_key` target is rejected `VALIDATION_ERROR` (mirrors
+ * human-only scoping; re-activating the disabled legacy `user-local` stub or an api_key principal
+ * outside `ISSUE_API_KEY`'s own lifecycle is never a valid call). Already-active is idempotent
+ * (mirrors `disablePrincipal`'s own already-disabled no-op above).
+ *
+ * @complexity O(1) — one lookup, one save.
+ * @overallScore 100
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function enablePrincipal(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        principalId: UUID;
+    };
+}): Promise<{
+    principal: PrincipalRecord;
+}>;
+/**
+ * `UPDATE_USER` (feature.spec.md ). Gated by `user.manage`; existing self-profile edits also
+ * accept `member.manage`. Only owners may edit owner targets — `email` only; `username`/`password` are not
+ * this transition's concern ( respectively). An absent or empty-string `email`
+ * clears the stored value to `undefined` ( — no distinct "blank but present" state).
+ *
+ * @complexity O(1) — one lookup, one save.
+ * @overallScore 100
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function updateUser(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        principalId: UUID;
+    };
+}, optional?: {
+    email?: string | undefined;
+}): Promise<{
+    user: UserRecord;
+}>;
+/**
+ * `RESET_USER_PASSWORD` (feature.spec.md ). Gated by **`user.manage`** only
+ * (resetting a credential is at least as sensitive as disabling the account, own reasoning). Hashes the new password identically to `CREATE_USER` (argon2id,
+ * ), then revokes every one of the target's active sessions (idempotent no-op if it has none,
+ * ) — a reset that left old sessions alive would not actually contain a compromised account.
+ *
+ * Refuses a THIRD PARTY resetting the seeded owner's password ( reasoning, same
+ * `OwnerRequiredError` `disablePrincipal` uses): `user.manage` is independently grantable and not
+ * owner-exclusive (`permissions.ts` — "Create/disable operator users and principals"), so without
+ * this check a caller holding only that one delegated permission could set a password of their own
+ * choosing on the seeded owner's account and log in as owner — a full takeover from a routine
+ * delegation. Checked before the password-policy validation so the refusal doesn't depend on the
+ * caller supplying a well-formed password first.
+ *
+ * Deliberately NOT unconditional the way `disablePrincipal`'s owner check is: the owner resetting
+ * ITS OWN password (`callerPrincipalId === principalId === seededOwnerPrincipalId`) is refused
+ * nothing — that self-service path is real, shipped infrastructure
+ * (`reset-admin-password-self-verified.ts`, driven by both the `HOST_ADMIN_RESET_PASSWORD`
+ * boot-time incident-recovery hook and the `backfill-reset-admin-password.ts` CLI script), added
+ * specifically to let an operator recover a locked-out owner account out-of-band. Disabling has no
+ * legitimate self-case (an owner disabling itself only ever stands the workspace down), so
+ * `disablePrincipal` can refuse unconditionally; a credential rotation the owner performs on itself
+ * is ordinary hygiene and the documented recovery path, so only a MISMATCHED caller — the actual
+ * escalation shape — is refused here.
+ *
+ * Deliberately NOT -clamped (unlike `disablePrincipal`'s second guard): a reset changes a
+ * credential, it never changes `status`, so it can never drop the workspace's active owner-`*`
+ * count — headcount guard has nothing to protect here.
+ *
+ * `input.seededOwnerPrincipalId` is the caller's job to resolve (`await deps.ownerPrincipalId` at
+ * the route layer, mirroring `disablePrincipal`'s own contract above) — this function takes the
+ * already-resolved id so it stays a plain, directly-testable function.
+ *
+ * @complexity O(s) in the target's session count, s = active session rows to revoke — bounded by
+ * the same operator-managed-roster scale assumption every other identity list call here makes.
+ * @overallScore 100
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function resetUserPassword(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        principalId: UUID;
+        password: string;
+        seededOwnerPrincipalId: UUID;
+    };
+}): Promise<{
+    user: UserRecord;
+}>;
+/**
+ * `UPDATE_ROLE` (feature.spec.md ). Gated by `role.manage`. A built-in target is
+ * refused `VALIDATION_ERROR` — extends existing undeletable/immutable/un-attachable-to
+ * rule to also cover un-renameable (same escalation shape: relabeling `viewer` to read as trusted
+ * is a social-engineering variant of what already blocks structurally).
+ *
+ * @complexity O(1) — one lookup, one save.
+ * @overallScore 100
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function updateRole(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        roleId: UUID;
+        name: string;
+    };
+}): Promise<{
+    role: RoleRecord;
+}>;
+/**
+ * `UPDATE_POLICY` (feature.spec.md ). Gated by `role.manage`. A built-in or
+ * `is_frozen` target is refused `VALIDATION_ERROR` — the frozen-policy half mirrors
+ * `WRITE_POLICY_PERMISSION`'s existing refusal : an issuance snapshot's identity is as
+ * immutable as its permission set. At least one of `name`/`description` must be present.
+ *
+ * @complexity O(1) — one lookup, one save.
+ * @overallScore 100
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function updatePolicy(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        policyId: UUID;
+    };
+}, optional?: {
+    name?: string | undefined;
+    description?: string | undefined;
+}): Promise<{
+    policy: PolicyRecord;
+}>;
+/**
+ * `DELETE_ROLE` (feature.spec.md ). Gated by `role.manage`. A built-in
+ * target is refused `VALIDATION_ERROR` (checked before the reference count, matching
+ * stated precedence). A still-referenced target (≥1 `principal_roles` row) is refused
+ * `IdentityConflictError` (409 `RESOURCE_CONFLICT`) — the reference check and the delete happen in
+ * one identity transaction ( atomicity, same isolation requirement as
+ * `disablePrincipal`'s owner-count guard above). Concurrent grant writers use the same port so
+ * no assignment can appear between the reference check and deletion.
+ *
+ * @complexity O(a) in the role's assignment count (`principalRoles.listByRoleId`) — bounded by the
+ * same operator-managed-roster assumption every other identity list call makes.
+ * @overallScore 100
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function deleteRole(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        roleId: UUID;
+    };
+}): Promise<void>;
+/**
+ * `DELETE_POLICY` (feature.spec.md ). Gated by `role.manage`. A
+ * built-in or `is_frozen` target is refused `VALIDATION_ERROR` (checked before the reference
+ * count). A still-referenced target (≥1 `role_policies` or `principal_policies` row) is refused
+ * `IdentityConflictError`. On success, cascades to the policy's OWN `policy_permissions` rows only
+ * (never a different policy's) before deleting the policy row itself. Both deletes and the
+ * reference guard share one transaction; failure rolls back the permission cascade.
+ *
+ * @complexity O(r + p) — role-reference count + principal-reference count, both bounded by the same
+ * operator-managed-roster assumption every other identity list call makes.
+ * @overallScore 100
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function deletePolicy(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        policyId: UUID;
+    };
+}): Promise<void>;
+/**
+ * `WRITE_POLICY_PERMISSION` (feature.spec.md, state.spec §3). First HTTP
+ * implementation of a transition specified since v0.5.3 ( — this is a route, not a
+ * re-specification). Gated by `role.manage`. Refuses an unregistered permission
+ * (`PermissionUnknownError`), a built-in or `is_frozen` parent policy, and
+ * (via the shared `assertGrantClamp`) a permission the caller does not itself hold unconstrained
+ * (`GrantExceedsIssuerError`).
+ *
+ * @complexity O(assertGrantClamp) — see that function's own doc (resolveEffectivePermissions +
+ * O(1) local filtering, one permission).
+ * @overallScore 100
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function writePolicyPermission(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        policyId: UUID;
+        permission: string;
+    };
+}, optional?: {
+    resourceType?: string | null;
+    constraintJson?: string | null;
+}): Promise<{
+    policyPermission: PolicyPermissionRecord;
+}>;
+/**
+ * `REMOVE_POLICY_PERMISSION` — the inverse of {@link writePolicyPermission}, and the
+ * transition whose absence made a policy's permission set append-only: the only way to shrink one
+ * was `deletePolicy` + recreate, which blocks outright the moment anything references the
+ * policy.
+ *
+ * Gated by `role.manage`, the same permission `writePolicyPermission` and `deletePolicy` require.
+ * Deliberately NOT clamped by `assertGrantClamp` : the clamp exists to stop a caller
+ * conferring authority it does not itself hold, and removal confers nothing — it is a strict
+ * de-escalation. Requiring the clamp here would mean an admin who cannot grant `content.write`
+ * also cannot take it back, which is the wrong direction for a safety rule. This is strictly less
+ * powerful than the already-unclamped `deletePolicy`, which drops EVERY permission row the policy
+ * has.
+ *
+ * Refuses a built-in or `is_frozen` parent policy, checked BEFORE the row lookup so
+ * a frozen policy reports why it is frozen rather than leaking whether the row exists. A row that
+ * is absent — or that exists but belongs to a DIFFERENT policy — is one and the same
+ * `IdentityNotFoundError`: membership is proven from `listByPolicyId`'s result, so a caller can
+ * never delete across a policy boundary by guessing an id.
+ *
+ * @complexity O(n) in the policy's own permission-row count (one `listByPolicyId`) — bounded by the
+ * same operator-managed-roster assumption every other identity list call makes.
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function removePolicyPermission(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        policyId: UUID;
+        policyPermissionId: UUID;
+    };
+}): Promise<void>;
+//# sourceMappingURL=admin-crud-service.d.ts.map