@jini-ai/cms 0.3.11 → 0.4.1

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

@@ -1,280 +0,0 @@
-import type { UUID } from "../core/ports.js";
-import type { AuthServiceDeps } from "./auth-service.js";
-import { type PolicyPermissionRecord, type PolicyRecord, type PrincipalRecord, type RoleRecord, type UserRecord } from "./types.js";
-/**
- * @file An amendment that completes the users/roles/policies admin CRUD surface
- * (feature.spec.md REQ-11/REQ-15..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 (AC-32). 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
- * INV-07-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).
- */
-/**
- * `DISABLE_PRINCIPAL` (feature.spec.md REQ-11, state.spec §3, AC-08/AC-21/AC-27). Gated by
- * `user.manage`. Refuses the seeded owner unconditionally (REQ-13's 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 (INV-08) — both checked, and the status update
- * performed, inside this one function body with no `await` yielded to another caller in between
- * (this codebase's established "atomic by construction" reasoning for a single-connection,
- * single-event-loop composition — same as `features/workspace/delete.ts`'s INV-03 guard).
- *
- * `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
- */
-export declare function disablePrincipal(required: {
-    deps: AuthServiceDeps;
-    input: {
-        workspaceId: UUID;
-        callerPrincipalId: UUID;
-        principalId: UUID;
-        seededOwnerPrincipalId: UUID;
-    };
-}): Promise<{
-    principal: PrincipalRecord;
-}>;
-/**
- * `ENABLE_PRINCIPAL` (feature.spec.md REQ-15, AC-27, EC-14). Gated by `user.manage`. Target must be
- * `kind='user'` — a `system`/`api_key` target is rejected `VALIDATION_ERROR` (mirrors AC-25b's
- * 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
- */
-export declare function enablePrincipal(required: {
-    deps: AuthServiceDeps;
-    input: {
-        workspaceId: UUID;
-        callerPrincipalId: UUID;
-        principalId: UUID;
-    };
-}): Promise<{
-    principal: PrincipalRecord;
-}>;
-/**
- * `UPDATE_USER` (feature.spec.md REQ-16, AC-28). Gated by `user.manage` **or** `member.manage`
- * (mirrors `CREATE_USER`'s admin-onboarding gate) — `email` only; `username`/`password` are not
- * this transition's concern (OQ-09 / REQ-17 respectively). An absent or empty-string `email`
- * clears the stored value to `undefined` (EC-17 — no distinct "blank but present" state).
- *
- * @complexity O(1) — one lookup, one save.
- * @overallScore 100
- */
-export declare function updateUser(required: {
-    deps: AuthServiceDeps;
-    input: {
-        workspaceId: UUID;
-        callerPrincipalId: UUID;
-        principalId: UUID;
-        email?: string | undefined;
-    };
-}): Promise<{
-    user: UserRecord;
-}>;
-/**
- * `RESET_USER_PASSWORD` (feature.spec.md REQ-17, AC-29, EC-16). Gated by **`user.manage`** only
- * (stricter than `updateUser` — resetting a credential is at least as sensitive as disabling the
- * account, REQ-17's own reasoning). Hashes the new password identically to `CREATE_USER` (argon2id,
- * INV-05), then revokes every one of the target's active sessions (idempotent no-op if it has none,
- * EC-16) — a reset that left old sessions alive would not actually contain a compromised account.
- *
- * Refuses a THIRD PARTY resetting the seeded owner's password (REQ-11/REQ-13's 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 `TOVU_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 INV-08-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 — INV-08's 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
- */
-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 REQ-18, AC-30). Gated by `role.manage`. A built-in target is
- * refused `VALIDATION_ERROR` — extends INV-06's 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 INV-06 already blocks structurally).
- *
- * @complexity O(1) — one lookup, one save.
- * @overallScore 100
- */
-export declare function updateRole(required: {
-    deps: AuthServiceDeps;
-    input: {
-        workspaceId: UUID;
-        callerPrincipalId: UUID;
-        roleId: UUID;
-        name: string;
-    };
-}): Promise<{
-    role: RoleRecord;
-}>;
-/**
- * `UPDATE_POLICY` (feature.spec.md REQ-18, AC-30). 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 (AC-26): 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
- */
-export declare function updatePolicy(required: {
-    deps: AuthServiceDeps;
-    input: {
-        workspaceId: UUID;
-        callerPrincipalId: UUID;
-        policyId: UUID;
-        name?: string | undefined;
-        description?: string | undefined;
-    };
-}): Promise<{
-    policy: PolicyRecord;
-}>;
-/**
- * `DELETE_ROLE` (feature.spec.md REQ-19/INV-09, AC-31, EC-15). Gated by `role.manage`. A built-in
- * target is refused `VALIDATION_ERROR` (checked before the reference count, matching AC-31's
- * stated precedence). A still-referenced target (≥1 `principal_roles` row) is refused
- * `IdentityConflictError` (409 `RESOURCE_CONFLICT`) — the reference check and the delete happen in
- * this one function body with no yielded `await` in between (INV-09's atomicity, same reasoning as
- * `disablePrincipal`'s owner-count guard above).
- *
- * @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
- */
-export declare function deleteRole(required: {
-    deps: AuthServiceDeps;
-    input: {
-        workspaceId: UUID;
-        callerPrincipalId: UUID;
-        roleId: UUID;
-    };
-}): Promise<void>;
-/**
- * `DELETE_POLICY` (feature.spec.md REQ-19/INV-09, AC-31, EC-15). 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.
- *
- * @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
- */
-export declare function deletePolicy(required: {
-    deps: AuthServiceDeps;
-    input: {
-        workspaceId: UUID;
-        callerPrincipalId: UUID;
-        policyId: UUID;
-    };
-}): Promise<void>;
-/**
- * `WRITE_POLICY_PERMISSION` (feature.spec.md INV-07, state.spec §3, AC-10/AC-24/AC-26). First HTTP
- * implementation of a transition specified since v0.5.3 (AC-32 — this is a route, not a
- * re-specification). Gated by `role.manage`. Refuses an unregistered permission
- * (`PermissionUnknownError`, REQ-03), a built-in or `is_frozen` parent policy (INV-06/AC-26), and
- * (via the shared `assertGrantClamp`) a permission the caller does not itself hold unconstrained
- * (INV-07, `GrantExceedsIssuerError`).
- *
- * @complexity O(assertGrantClamp) — see that function's own doc (resolveEffectivePermissions +
- * O(1) local filtering, one permission).
- * @overallScore 100
- */
-export declare function writePolicyPermission(required: {
-    deps: AuthServiceDeps;
-    input: {
-        workspaceId: UUID;
-        callerPrincipalId: UUID;
-        policyId: UUID;
-        permission: string;
-        resourceType?: string | null;
-        constraintJson?: string | null;
-    };
-}): Promise<{
-    policyPermission: PolicyPermissionRecord;
-}>;
-/**
- * `REMOVE_POLICY_PERMISSION` (OQ-10) — 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 INV-09 blocks outright the moment anything references the
- * policy.
- *
- * Gated by `role.manage`, the same permission `writePolicyPermission` and `deletePolicy` require.
- * Deliberately NOT clamped by `assertGrantClamp` (INV-07): 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 (INV-06/AC-26), 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.
- */
-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