@jini-ai/user-management 0.2.0

package/dist/server/authorize.d.ts

@@ -0,0 +1,92 @@
+import type { UUID } from "@jini-ai/core/primitives";
+import type { PolicyPermissionRepoPort, PrincipalPolicyRepoPort, PrincipalRepoPort, PrincipalRoleRepoPort, RolePolicyRepoPort } from "../core/ports.js";
+import type { PolicyPermissionRecord } from "../core/types.js";
+/**
+ * @file `authorize` — the RBAC evaluator.
+ *
+ * Purpose:
+ * Ordinary core function, deliberately NOT a port (one evaluator —
+ * "no PolicyPort"). The command gateway calls this before every
+ * mutation; it is deterministic and side-effect free given the
+ * repo snapshot (state.spec §4).
+ *
+ * How it relates to the project:
+ * - `command.ts`'s `executeCommand` calls a bound closure of this shape
+ * (typed there as `AuthorizeFn`, kept generic so `core/commands` never
+ * imports this feature-level library — see that file's header).
+ * - Route handlers call it directly for mutations that do not flow through
+ * the command gateway (this pass: `members` disable — see the handoff).
+ *
+ * Architectural role:
+ * Implements the matcher precedence in behavior.spec §1.1 exactly:
+ * disabled-principal short-circuit > owner wildcard > exact matching row >
+ * fail-closed default. Fail-closed extensibility: a non-null
+ * `constraintJson` is never treated as unconstrained, and a `resourceType`
+ * mismatch/absence is never treated as a global grant.
+ * See docs/decisions/DR-001-identity-and-session-boundary.md.
+ */
+/** The context an authorization decision is evaluated against. See docs/decisions/DR-001-identity-and-session-boundary.md. */
+export interface AuthorizeContext {
+    workspaceId: UUID;
+    entityType?: string;
+    entityId?: UUID;
+}
+/** `authorize`'s result — always fail-closed on `allowed: false`. See docs/decisions/DR-001-identity-and-session-boundary.md. */
+export interface AuthorizeResult {
+    allowed: boolean;
+    /** Machine-readable reason: `principal_disabled | no_grant | resource_scope_mismatch | unconstrained_deny | owner_wildcard | matched`. */
+    reason: string;
+}
+/** Repos `authorize()`/`resolveEffectivePermissions()` read. Not a port bag with alternate adapters — see file header. */
+export interface AuthorizeDeps {
+    principals: PrincipalRepoPort;
+    principalRoles: PrincipalRoleRepoPort;
+    rolePolicies: RolePolicyRepoPort;
+    principalPolicies: PrincipalPolicyRepoPort;
+    policyPermissions: PolicyPermissionRepoPort;
+}
+/**
+ * Resolve a principal's effective permission rows: the union of (a) its
+ * roles' policies' permissions and (b) policies attached directly via
+ * `principal_policies` (behavior.spec §1.2). Scoped to `workspaceId` by
+ * construction (every repo call below is workspace-scoped).
+ *
+ * @complexity O(r*p + d) round trips, r = roles held, p = policies per role,
+ * d = direct policy attachments — all expected small (a handful of rows per
+ * principal). No caller-unbounded collection is walked.
+ * @overallScore 100
+ */
+export declare function resolveEffectivePermissions(required: {
+    deps: AuthorizeDeps;
+    principalId: UUID;
+    workspaceId: UUID;
+}): Promise<PolicyPermissionRecord[]>;
+/**
+ * The RBAC decision. Fail-closed: `allowed` defaults to `false` and
+ * only ever flips to `true` on an explicit disabled-short-circuit-cleared,
+ * matching row.
+ *
+ * Precedence (behavior.spec §1.1, highest to lowest):
+ * 1. Disabled principal -> `false`, `principal_disabled` (overrides all grants).
+ * 2. An unconstrained owner `"*"` row -> `true`, `owner_wildcard`.
+ * 3. An exact matching row (permission + workspace + resource-scope + no
+ * constraint) -> `true`, `matched`.
+ * 4. Fail-closed default -> `false`, with the most specific diagnostic reason
+ * available among same-permission candidates (`unconstrained_deny` over
+ * `resource_scope_mismatch` over `no_grant` — an inferred, undocumented-but-
+ * reasonable tie-break; the spec only pins each reason in isolation, see
+ * ).
+ *
+ * @complexity O(resolveEffectivePermissions) + O(k) local filtering, k = the
+ * principal's effective row count (small, bounded by grants a workspace
+ * administrator creates by hand).
+ * @overallScore 100
+ * See docs/decisions/DR-001-identity-and-session-boundary.md.
+ */
+export declare function authorize(required: {
+    deps: AuthorizeDeps;
+    principalId: UUID;
+    permission: string;
+    context: Pick<AuthorizeContext, "workspaceId">;
+}, optional?: Omit<AuthorizeContext, "workspaceId">): Promise<AuthorizeResult>;
+//# sourceMappingURL=authorize.d.ts.map

package/dist/server/authorize.js

@@ -0,0 +1,96 @@
+/**
+ * Resolve a principal's effective permission rows: the union of (a) its
+ * roles' policies' permissions and (b) policies attached directly via
+ * `principal_policies` (behavior.spec §1.2). Scoped to `workspaceId` by
+ * construction (every repo call below is workspace-scoped).
+ *
+ * @complexity O(r*p + d) round trips, r = roles held, p = policies per role,
+ * d = direct policy attachments — all expected small (a handful of rows per
+ * principal). No caller-unbounded collection is walked.
+ * @overallScore 100
+ */
+export async function resolveEffectivePermissions(required) {
+    const { deps, principalId, workspaceId } = required;
+    const roleLinks = await deps.principalRoles.listByPrincipalId({ workspaceId, principalId });
+    const rolePermissionGroups = await Promise.all(roleLinks.map(async (roleLink) => {
+        const rolePolicyLinks = await deps.rolePolicies.listByRoleId({
+            workspaceId,
+            roleId: roleLink.roleId,
+        });
+        const policyPermissionGroups = await Promise.all(rolePolicyLinks.map((rolePolicyLink) => deps.policyPermissions.listByPolicyId({ workspaceId, policyId: rolePolicyLink.policyId })));
+        return policyPermissionGroups.flat();
+    }));
+    const directLinks = await deps.principalPolicies.listByPrincipalId({ workspaceId, principalId });
+    const directPermissionGroups = await Promise.all(directLinks.map((directLink) => deps.policyPermissions.listByPolicyId({ workspaceId, policyId: directLink.policyId })));
+    return [...rolePermissionGroups.flat(), ...directPermissionGroups.flat()];
+}
+/**
+ * True iff `row` is an exact, unconstrained-or-scope-matching grant of
+ * `permission` in `context` (state.spec §4 `matchesRow`). Assumes `row` has
+ * already passed the owner-wildcard check upstream — this never special-cases
+ * `"*"`.
+ */
+function matchesRow(row, permission, context) {
+    if (row.permission !== permission)
+        return false;
+    if (row.constraintJson != null)
+        return false;
+    if (row.resourceType != null && row.resourceType !== context.entityType)
+        return false;
+    return true;
+}
+/**
+ * The RBAC decision. Fail-closed: `allowed` defaults to `false` and
+ * only ever flips to `true` on an explicit disabled-short-circuit-cleared,
+ * matching row.
+ *
+ * Precedence (behavior.spec §1.1, highest to lowest):
+ * 1. Disabled principal -> `false`, `principal_disabled` (overrides all grants).
+ * 2. An unconstrained owner `"*"` row -> `true`, `owner_wildcard`.
+ * 3. An exact matching row (permission + workspace + resource-scope + no
+ * constraint) -> `true`, `matched`.
+ * 4. Fail-closed default -> `false`, with the most specific diagnostic reason
+ * available among same-permission candidates (`unconstrained_deny` over
+ * `resource_scope_mismatch` over `no_grant` — an inferred, undocumented-but-
+ * reasonable tie-break; the spec only pins each reason in isolation, see
+ * ).
+ *
+ * @complexity O(resolveEffectivePermissions) + O(k) local filtering, k = the
+ * principal's effective row count (small, bounded by grants a workspace
+ * administrator creates by hand).
+ * @overallScore 100
+ * See docs/decisions/DR-001-identity-and-session-boundary.md.
+ */
+export async function authorize(required, optional = {}) {
+    const { deps, principalId, permission } = required;
+    const context = { ...required.context, ...optional };
+    const principal = await deps.principals.findById({ workspaceId: context.workspaceId, id: principalId });
+    if (!principal || principal.status === "disabled") {
+        return { allowed: false, reason: "principal_disabled" };
+    }
+    const effectiveRows = await resolveEffectivePermissions({
+        deps,
+        principalId,
+        workspaceId: context.workspaceId,
+    });
+    const hasUnconstrainedWildcard = effectiveRows.some((row) => row.permission === "*" && row.resourceType == null && row.constraintJson == null);
+    if (hasUnconstrainedWildcard) {
+        return { allowed: true, reason: "owner_wildcard" };
+    }
+    const candidates = effectiveRows.filter((row) => row.permission === permission);
+    if (candidates.length === 0) {
+        return { allowed: false, reason: "no_grant" };
+    }
+    const matched = candidates.some((row) => matchesRow(row, permission, context));
+    if (matched) {
+        return { allowed: true, reason: "matched" };
+    }
+    if (candidates.some((row) => row.constraintJson != null)) {
+        return { allowed: false, reason: "unconstrained_deny" };
+    }
+    if (candidates.some((row) => row.resourceType != null)) {
+        return { allowed: false, reason: "resource_scope_mismatch" };
+    }
+    return { allowed: false, reason: "no_grant" };
+}
+//# sourceMappingURL=authorize.js.map

package/dist/server/grant-service.d.ts

@@ -0,0 +1,219 @@
+import type { UUID } from "@jini-ai/core/primitives";
+import { type AuthorizeDeps } from "./authorize.js";
+import type { AuthServiceDeps } from "./auth-service.js";
+import type { IdentityRepos } from "../core/ports.js";
+import { type PolicyRecord, type PrincipalPolicyRecord, type PrincipalRecord, type PrincipalRoleRecord, type RoleRecord, type UserRecord } from "../core/types.js";
+/**
+ * @file Human grant-writing transitions (state.spec.md §3): `CREATE_USER`,
+ * `CREATE_ROLE`, `CREATE_POLICY`, `ASSIGN_ROLE`, `ATTACH_POLICY`.
+ *
+ * Purpose:
+ * The only usable identity principal before this file was the seeded owner —
+ * there was no API path to create a second user or grant/change permissions.
+ * These five functions are that path, following `auth-service.ts`'s exact
+ * shape (`{ deps: AuthServiceDeps, input: {...} }`, one exported async
+ * function per transition, plain `Error` subclasses for control flow).
+ *
+ * Out of scope (deferred, see the dispatch directive): `ISSUE_API_KEY`,
+ * `CREATE_PRINCIPAL` (api_key/agent principal creation), agent/api_key
+ * delegation, `WRITE_POLICY_PERMISSION`, `DISABLE_PRINCIPAL`.
+ *
+ * Architectural role:
+ * Ordinary core functions, not ports (mirrors `auth-service.ts`'s reasoning —
+ * grant-writing logic has one implementation). Each function calls
+ * `authorize`/`resolveEffectivePermissions` from `authorize.ts` itself
+ * (rather than pushing the gate into the route layer, the way
+ * `members/disable.ts`'s route does) so the caller-permission gate and the
+ * clamp are exercised directly by unit tests, no HTTP harness needed.
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+/**
+ * Assemble the `AuthorizeDeps` bag `authorize()`/`resolveEffectivePermissions()` expect from the
+ * flat `IdentityRepos` bag. Exported so `admin-crud-service.ts`'s new transitions
+ * (`ENABLE_PRINCIPAL`/`UPDATE_USER`/`RESET_USER_PASSWORD`/`UPDATE_ROLE`/`UPDATE_POLICY`/
+ * `DELETE_ROLE`/`DELETE_POLICY`/`WRITE_POLICY_PERMISSION`/`DISABLE_PRINCIPAL`) reuse the identical
+ * gate/clamp logic rather than duplicating it — same file-split reasoning `auth-service.ts` and
+ * `grant-service.ts` already use (one shared helper set, two transition files).
+ */
+export declare function authorizeDepsFrom(repos: IdentityRepos): AuthorizeDeps;
+/** True iff `principalId` holds the owner wildcard `*` (unconstrained) in its effective set. */
+export declare function principalHoldsOwnerWildcard(required: {
+    deps: AuthServiceDeps;
+    workspaceId: UUID;
+    principalId: UUID;
+}): Promise<boolean>;
+/** Owner-account writes reuse the same unconstrained wildcard test as the active-owner floor. */
+export declare function assertOwnerTargetMayBeModified(required: {
+    deps: AuthServiceDeps;
+    workspaceId: UUID;
+    callerPrincipalId: UUID;
+    principalId: UUID;
+}): Promise<void>;
+/**
+ * Fail-closed caller-permission gate shared by every transition in this file.
+ * Throws `IdentityForbiddenError` (403 `FORBIDDEN`) unless the caller holds
+ * at least one of `permissions` (an OR gate where the transition permits it;
+ * operator creation requires `user.manage`, while self-profile edits retain their existing OR).
+ *
+ * @complexity O(p) `authorize()` calls, p = `permissions.length` (1 or 2 in
+ * every caller this pass) — each itself O(resolveEffectivePermissions), see
+ * that function's doc.
+ * @overallScore 100
+ */
+export declare function assertCallerHasAnyPermission(required: {
+    deps: AuthServiceDeps;
+    workspaceId: UUID;
+    callerPrincipalId: UUID;
+    permissions: readonly string[];
+}): Promise<void>;
+/**
+ * The grant-authority clamp (feature.spec.md, state.spec §3
+ * `ASSIGN_ROLE`/`ATTACH_POLICY` rows): every permission in `conferredPermissions`
+ * must be a matching effective row the caller holds unconstrained
+ * (`resourceType`/`constraintJson` both null; owner's `*` qualifies for all).
+ * A permission held only conditionally (resource-scoped or constraint-bound)
+ * cannot be delegated. Throws `GrantExceedsIssuerError` (403
+ * `GRANT_EXCEEDS_ISSUER`) naming every offending permission, and writes no
+ * grant row (caller does the write only after this resolves).
+ *
+ * @complexity O(resolveEffectivePermissions) + O(k) local filtering, k =
+ * `conferredPermissions.length` (bounded by one role's/policy's permission
+ * rows — a handful, per `identity/INFO.md`'s scale assumptions).
+ * @overallScore 100
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function assertGrantClamp(required: {
+    deps: AuthServiceDeps;
+    workspaceId: UUID;
+    callerPrincipalId: UUID;
+    conferredPermissions: readonly string[];
+}): Promise<void>;
+/**
+ * `CREATE_USER` (state.spec §3). Atomically mints a NEW
+ * `kind='user'` principal and its `users` row — the `principalId` is always
+ * generated here, never caller-supplied, so this transition can never attach
+ * a credential to a pre-existing principal (the privilege-escalation
+ * class: an earlier draft let an admin bind a password to the seeded owner
+ * principal and log in as owner). Gated by `user.manage`; front-end
+ * `member.manage` never authorizes minting an operator credential.
+ *
+ * "Atomically" here means structurally, not via a DB transaction — the
+ * in-memory adapters have no cross-repo transaction (same disclosed gap as
+ * `seed.ts`/`executeCommand`'s compensating-rollback path). The invariant
+ * that actually matters (no credential ever attaches to an existing
+ * principal) holds regardless, because `principalId` is generated inline and
+ * the password is hashed before either row is written, so a hashing failure
+ * leaves no orphan principal. A future SQLite adapter wraps both writes in
+ * one real transaction (port/adapter rule-of-two) without changing this contract.
+ *
+ * @complexity O(1) — one permission check, one username lookup, one hash,
+ * two saves.
+ * @overallScore 100
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function createUser(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        username: string;
+        password: string;
+    };
+}, optional?: {
+    email?: string | undefined;
+}): Promise<{
+    principal: PrincipalRecord;
+    user: UserRecord;
+}>;
+/**
+ * `CREATE_ROLE` (state.spec §3). Gated by `role.manage`. Always mints
+ * `isBuiltin=false` — built-ins are SEED-only and immutable.
+ *
+ * Deviation from the state.spec §3 table (disclosed): that row lists
+ * `name`, `description?` jointly for `CREATE_ROLE`/`CREATE_POLICY`, but
+ * `RoleRecord` (types.ts, frozen before this task) has no `description`
+ * field — only `PolicyRecord` does. `createRole` therefore takes `name`
+ * only; `createPolicy` below takes both.
+ *
+ * @complexity O(1) — one permission check, one save.
+ * @overallScore 100
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function createRole(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        name: string;
+    };
+}): Promise<{
+    role: RoleRecord;
+}>;
+/**
+ * `CREATE_POLICY` (state.spec §3). Gated by `role.manage`. Always mints
+ * `isBuiltin=false` and `isFrozen=false` — only the (out-of-scope this pass)
+ * `ISSUE_API_KEY` transition ever mints `isFrozen=true` policies.
+ *
+ * @complexity O(1) — one permission check, one save.
+ * @overallScore 100
+ */
+export declare function createPolicy(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        name: string;
+    };
+}, optional?: {
+    description?: string | undefined;
+}): Promise<{
+    policy: PolicyRecord;
+}>;
+/**
+ * `ASSIGN_ROLE` (state.spec §3). Gated by `role.manage`;
+ * target must be a `kind='user'` principal; the clamp must
+ * pass over every permission carried by the role's policies — so
+ * assigning the built-in `owner` role requires the caller to already hold
+ * the wildcard `*` (owner-only). No row is written on any rejection.
+ *
+ * @complexity O(resolveEffectivePermissions) + O(role's rolePolicy count)
+ * round trips to gather conferred permissions — both bounded by the small,
+ * hand-authored grant graph this system assumes (see `identity/INFO.md`).
+ * @overallScore 100
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function assignRole(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        principalId: UUID;
+        roleId: UUID;
+    };
+}): Promise<{
+    assignment: PrincipalRoleRecord;
+}>;
+/**
+ * `ATTACH_POLICY` (state.spec §3). Gated by
+ * `role.manage`; target must be a `kind='user'` principal; the
+ * clamp must pass over every permission the policy carries —
+ * attaching the built-in `owner` policy requires the caller to already hold
+ * `*` (owner-only). No row is written on any rejection.
+ *
+ * @complexity O(resolveEffectivePermissions) + O(policy's permission row
+ * count) — both bounded, see `assignRole`'s doc.
+ * @overallScore 100
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ */
+export declare function attachPolicy(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        callerPrincipalId: UUID;
+        principalId: UUID;
+        policyId: UUID;
+    };
+}): Promise<{
+    attachment: PrincipalPolicyRecord;
+}>;
+//# sourceMappingURL=grant-service.d.ts.map