@jini-ai/user-management 0.2.0

package/dist/server/password-policy.js

@@ -0,0 +1,66 @@
+/**
+ * @file Password policy: no minimum length, no composition rules — presence and an upper bound only.
+ *
+ * Owner decision: the previous NIST SP 800-63B-aligned 12-character minimum has been removed.
+ * This module no longer enforces composition rules (mandatory uppercase, digit, or symbol) either
+ * — that predates this change and remains deliberate, since composition rules measurably push
+ * people toward predictable, guessable patterns ("Password1!") rather than genuinely stronger
+ * secrets. What remains is the minimum a credential system can enforce at all: a password must be
+ * non-empty, and is capped at `MAX_PASSWORD_LENGTH` as a defense-in-depth bound (see that
+ * constant's own doc).
+ *
+ * `createUser` (`grant-service.ts`) and `resetUserPassword` (`admin-crud-service.ts`) are the
+ * identity system's only two write paths that ever set a password, confirmed by tracing the
+ * whole call graph — both call this module.
+ *
+ * Two things this deliberately does NOT do, both load-bearing:
+ * - Never reaches `seed.ts`'s first-boot owner password. `seedIdentity` hashes it directly
+ *   (`deps.hasher.hash(ownerPassword)`, `seed.ts:317`) and calls neither `createUser` nor
+ *   `resetUserPassword` — confirmed before writing this module. That separation is intentional
+ *   to preserve here: the host chooses the first-boot owner password (`SeedIdentityInput` requires
+ *   it and supplies no default), and an existing installation is already authenticating with
+ *   whatever it chose. Enforcing this policy on that path would lock out every such installation
+ *   whose chosen value predates the policy.
+ * - Never re-validates at login. This is a write-time policy — `login`/`verify` never call it.
+ *   An account whose password predates this policy (or was seeded) must keep authenticating.
+ */
+/**
+ * Generous upper bound — not itself a security requirement (argon2id's cost is tuned by its
+ * `memoryCost`/`timeCost`/`parallelism` parameters, not by input size — see `hasher.ts`'s own
+ * `@complexity` note), but a defense-in-depth cap on how large a string this service will accept
+ * and pass to the hasher at all, independent of whatever limit (if any) sits in front of it at
+ * the HTTP layer. Comfortably above any realistic human-typed passphrase.
+ */
+export const MAX_PASSWORD_LENGTH = 512;
+/**
+ * Validates `password` against the presence-and-upper-bound-only policy.
+ *
+ * Measures length in Unicode CODE POINTS (`[...password].length`), not UTF-16 code units
+ * (`password.length`): a passphrase built from astral-plane characters (many emoji, some
+ * CJK/historic scripts) is represented as a surrogate pair per character in a JS string, so plain
+ * `.length` overcounts those characters relative to what a human typing them perceives — the same
+ * reasoning that applies to `MAX_PASSWORD_LENGTH` below applies to the emptiness check here, since
+ * both compare this same code-point count. No trimming, no character allowlist: every printable
+ * character, including leading/trailing spaces and full Unicode, is accepted as typed. Silently
+ * altering the input (trimming, stripping) would make the stored credential differ from the
+ * secret the operator actually chose.
+ *
+ * @returns `null` if `password` satisfies the policy, otherwise an operator-facing message
+ * stating the requirement plainly — used verbatim as the thrown `IdentityValidationError`'s
+ * message by both call sites, and rendered as-is through the admin's `describeApiError` layer.
+ *
+ * @complexity O(n) in the password's length — spreading a string into code points is a single
+ * linear pass, which is the minimum work a correct (non-UTF-16-code-unit) count requires.
+ * @overallScore 100
+ */
+export function validatePasswordPolicy({ password }) {
+    const length = [...password].length;
+    if (length === 0) {
+        return "Password is required.";
+    }
+    if (length > MAX_PASSWORD_LENGTH) {
+        return `Password must be no more than ${MAX_PASSWORD_LENGTH} characters.`;
+    }
+    return null;
+}
+//# sourceMappingURL=password-policy.js.map

package/dist/server/permission-migrations.d.ts

@@ -0,0 +1,84 @@
+import { type PermissionMigration } from '../core/builtin-permissions.js';
+import type { IdGenerator, UUID } from "@jini-ai/core/primitives";
+import type { IdentityTransactionPort, PolicyPermissionRepoPort, PolicyRepoPort } from "../core/ports.js";
+/**
+ * @file Shared deprecate-old/grant-new permission migration mechanism
+ * (generalized from the `settings.write` ->
+ * `settings.definitions.manage` precedent already shipped ad hoc in
+ * `identity/seed.ts`/`identity/permissions.ts`; see
+ * `docs/decisions/permission-catalog-migration.md`).
+ *
+ * Purpose:
+ * A permission-string rename/split after real grants exist is a breaking
+ * migration. This module is
+ * the one place that fan-out runs, so Menus/Members/Analytics/Integrations
+ * remediation efforts each register their own `{from, to}` pair here instead of
+ * hand-rolling a fourth divergent copy of the same fix.
+ *
+ * How it relates to the project:
+ * - `registerPermissionMigration`/`listPermissionMigrations` are a small,
+ * in-process registry — pure metadata, no I/O, mirrors
+ * `permissions.ts`'s `PermissionCatalog.register` overwrite semantics.
+ * - `migrateDeprecatedPermissionGrants` is the actual grant fan-out: for
+ * every registered pair, every policy holding `from` gets every string in
+ * `to` it doesn't already hold. It is deliberately, structurally
+ * additive-only — there is no delete/update call against
+ * `policy_permissions` anywhere in this file.
+ * - Feature-agnostic by design: this module has zero knowledge of
+ * `navigation`/`settings`/any specific feature. Callers (e.g.
+ * `identity/permissions.ts`) register their own pairs.
+ *
+ * Architectural role:
+ * Security-adjacent domain logic (a bug here could fail-open (grant more than
+ * intended) or fail-closed (a policy silently missing a needed grant) across every
+ * feature that reuses it). The additive-only design bounds the fail-closed
+ * direction to "a required new permission is missing," never "an existing
+ * permission is removed." See `__tests__/permission-migrations.test.ts` for
+ * the dedicated fixture-driven certification required before any
+ * caller wires this into a live boot path.
+ * See docs/decisions/DR-003-additive-permission-migration.md.
+ */
+export type { PermissionMigration } from '../core/builtin-permissions.js';
+export interface MigrateDeprecatedPermissionGrantsDeps {
+    /** Bound to the same storage as both repository ports; required before any migration work. */
+    transactions: IdentityTransactionPort;
+    policyPermissions: PolicyPermissionRepoPort;
+    policies: PolicyRepoPort;
+    idGen: IdGenerator;
+    workspaceId: UUID;
+}
+export interface MigrateDeprecatedPermissionGrantsResult {
+    /** Total new `policy_permissions` rows written across every policy and every registered pair. */
+    migratedGrantCount: number;
+}
+/**
+ * Register a `{from, to, reason}` rename/split pair for later fan-out.
+ * Idempotent: re-registering the same `from` overwrites the prior entry
+ * rather than duplicating it (matches `PermissionCatalog.register`'s
+ * existing overwrite semantics, `identity/permissions.ts`).
+ *
+ * @complexity O(1).
+ * @overallScore 100
+ */
+export declare function registerPermissionMigration(migration: PermissionMigration): void;
+/** Enumerate every registered migration pair. */
+export declare function listPermissionMigrations(_required: Record<string, never>): PermissionMigration[];
+/**
+ * For every registered `{from, to}` pair, for every policy in the workspace
+ * holding `from`, ensure every string in `to` is also granted — adding only
+ * the rows that are missing. Never removes or mutates `from` (or any other
+ * existing row) — additive-only by construction. The entire fan-out runs in
+ * one identity transaction, so a failed or partial run restores the previous state rather
+ * than committing some target grants while withholding others.
+ *
+ * Safe to call on every boot (idempotent): a rerun with nothing new to add
+ * returns `migratedGrantCount: 0` (mirrors `migrateLegacyPresentationSettings`'s
+ * boot-safety precedent).
+ *
+ * @complexity O(p * m) where p = policies in the workspace, m = registered
+ * migration pairs; both are small, bounded collections in this app's shape.
+ * @overallScore 100
+ * See docs/decisions/DR-003-additive-permission-migration.md.
+ */
+export declare function migrateDeprecatedPermissionGrants(deps: MigrateDeprecatedPermissionGrantsDeps): Promise<MigrateDeprecatedPermissionGrantsResult>;
+//# sourceMappingURL=permission-migrations.d.ts.map

package/dist/server/permission-migrations.js

@@ -0,0 +1,77 @@
+import { inIdentityTransaction } from "./identity-transaction.js";
+import { BUILTIN_PERMISSION_MIGRATIONS } from '../core/builtin-permissions.js';
+/** Module-singleton registry — keyed by `from` so re-registration overwrites (idempotent, matches `PermissionCatalog.register`). */
+const registry = new Map(BUILTIN_PERMISSION_MIGRATIONS.map((migration) => [migration.from, migration]));
+/**
+ * Register a `{from, to, reason}` rename/split pair for later fan-out.
+ * Idempotent: re-registering the same `from` overwrites the prior entry
+ * rather than duplicating it (matches `PermissionCatalog.register`'s
+ * existing overwrite semantics, `identity/permissions.ts`).
+ *
+ * @complexity O(1).
+ * @overallScore 100
+ */
+export function registerPermissionMigration(migration) {
+    registry.set(migration.from, migration);
+}
+/** Enumerate every registered migration pair. */
+export function listPermissionMigrations(_required) {
+    return [...registry.values()];
+}
+/**
+ * For every registered `{from, to}` pair, for every policy in the workspace
+ * holding `from`, ensure every string in `to` is also granted — adding only
+ * the rows that are missing. Never removes or mutates `from` (or any other
+ * existing row) — additive-only by construction. The entire fan-out runs in
+ * one identity transaction, so a failed or partial run restores the previous state rather
+ * than committing some target grants while withholding others.
+ *
+ * Safe to call on every boot (idempotent): a rerun with nothing new to add
+ * returns `migratedGrantCount: 0` (mirrors `migrateLegacyPresentationSettings`'s
+ * boot-safety precedent).
+ *
+ * @complexity O(p * m) where p = policies in the workspace, m = registered
+ * migration pairs; both are small, bounded collections in this app's shape.
+ * @overallScore 100
+ * See docs/decisions/DR-003-additive-permission-migration.md.
+ */
+export async function migrateDeprecatedPermissionGrants(deps) {
+    const migrations = listPermissionMigrations({});
+    if (migrations.length === 0)
+        return { migratedGrantCount: 0 };
+    return inIdentityTransaction({
+        transactions: deps.transactions,
+        workspaceId: deps.workspaceId,
+        execute: async () => {
+            const policies = await deps.policies.list({ workspaceId: deps.workspaceId });
+            let migratedGrantCount = 0;
+            for (const policy of policies) {
+                const existing = await deps.policyPermissions.listByPolicyId({
+                    workspaceId: deps.workspaceId,
+                    policyId: policy.id,
+                });
+                const held = new Set(existing.map((row) => row.permission));
+                for (const migration of migrations) {
+                    if (!held.has(migration.from))
+                        continue;
+                    for (const toPermission of migration.to) {
+                        if (held.has(toPermission))
+                            continue;
+                        await deps.policyPermissions.save({
+                            id: deps.idGen.newId(),
+                            workspaceId: deps.workspaceId,
+                            policyId: policy.id,
+                            permission: toPermission,
+                            resourceType: null,
+                            constraintJson: null,
+                        });
+                        held.add(toPermission);
+                        migratedGrantCount += 1;
+                    }
+                }
+            }
+            return { migratedGrantCount };
+        },
+    });
+}
+//# sourceMappingURL=permission-migrations.js.map

package/dist/server/repo.memory-transactions.d.ts

@@ -0,0 +1,16 @@
+import type { IdentityRepos, IdentityTransactionPort } from '../core/ports.js';
+/**
+ * Wrap a complete memory repository bag with one serialization queue and rollback snapshots.
+ * Use only the returned repositories after binding: retained raw handles bypass isolation.
+ * Every ordinary read/write also joins the queue, so an assignment outside a service cannot
+ * race a guarded delete and readers cannot observe uncommitted changes. This is a dev/test
+ * adapter; durable hosts supply their own transaction port over their own storage connection.
+ */
+export declare function createTransactionalInMemoryIdentityRepos(required: {
+    repos: Omit<IdentityRepos, "transactions"> & {
+        transactions?: IdentityTransactionPort;
+    };
+}): IdentityRepos & {
+    transactions: IdentityTransactionPort;
+};
+//# sourceMappingURL=repo.memory-transactions.d.ts.map

package/dist/server/repo.memory-transactions.js

@@ -0,0 +1,79 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { InMemoryIdentityRows } from './repo.memory.js';
+/**
+ * Wrap a complete memory repository bag with one serialization queue and rollback snapshots.
+ * Use only the returned repositories after binding: retained raw handles bypass isolation.
+ * Every ordinary read/write also joins the queue, so an assignment outside a service cannot
+ * race a guarded delete and readers cannot observe uncommitted changes. This is a dev/test
+ * adapter; durable hosts supply their own transaction port over their own storage connection.
+ */
+export function createTransactionalInMemoryIdentityRepos(required) {
+    if (required.repos.transactions)
+        throw new Error('identity repositories are already bound to a transaction port');
+    const context = new AsyncLocalStorage();
+    let tail = Promise.resolve();
+    const stores = Object.entries(required.repos).filter(([key]) => key !== 'transactions');
+    for (const [, repo] of stores) {
+        if (!(repo instanceof InMemoryIdentityRows)) {
+            throw new Error('memory transactions require in-memory identity repositories');
+        }
+    }
+    /** Preserve queue progress after rejection; descendants of a completed body cannot bypass it. */
+    async function exclusive(execute) {
+        if (context.getStore()?.active)
+            return execute();
+        const previous = tail;
+        let release;
+        tail = new Promise(resolve => { release = resolve; });
+        await previous;
+        const scope = { active: true };
+        try {
+            return await context.run(scope, execute);
+        }
+        finally {
+            scope.active = false;
+            release();
+        }
+    }
+    const transactions = {
+        run: ({ execute }) => exclusive(async () => {
+            const snapshots = stores.map(([, repo]) => {
+                if (!(repo instanceof InMemoryIdentityRows))
+                    throw new Error('memory transactions require in-memory identity repositories');
+                const rows = repo.snapshotRows({});
+                return { restore: () => repo.restoreRows({ rows }) };
+            });
+            try {
+                return await execute();
+            }
+            catch (error) {
+                for (const snapshot of snapshots)
+                    snapshot.restore();
+                throw error;
+            }
+        }),
+    };
+    function wrap(repo) {
+        return new Proxy(repo, {
+            get(target, property, receiver) {
+                const member = Reflect.get(target, property, receiver);
+                if (typeof member !== 'function')
+                    return member;
+                return (...args) => exclusive(async () => {
+                    // Detach inputs/outputs so a row reference outside the queue cannot mutate stored state.
+                    const result = await Reflect.apply(member, target, structuredClone(args));
+                    return structuredClone(result);
+                });
+            },
+        });
+    }
+    const repos = {
+        principals: wrap(required.repos.principals), users: wrap(required.repos.users),
+        sessions: wrap(required.repos.sessions), roles: wrap(required.repos.roles),
+        policies: wrap(required.repos.policies), policyPermissions: wrap(required.repos.policyPermissions),
+        rolePolicies: wrap(required.repos.rolePolicies), principalRoles: wrap(required.repos.principalRoles),
+        principalPolicies: wrap(required.repos.principalPolicies),
+    };
+    return { ...repos, transactions };
+}
+//# sourceMappingURL=repo.memory-transactions.js.map

package/dist/server/repo.memory.d.ts

@@ -0,0 +1,186 @@
+import type { PolicyPermissionRecord, PolicyRecord, PrincipalPolicyRecord, PrincipalRecord, PrincipalRoleRecord, RolePolicyRecord, RoleRecord, SessionRecord, UserRecord } from "../core/types.js";
+import type { PolicyPermissionRepoPort, PolicyRepoPort, PrincipalPolicyRepoPort, PrincipalRepoPort, PrincipalRoleRepoPort, RolePolicyRepoPort, RoleRepoPort, SessionRepoPort, UserRepoPort } from "../core/ports.js";
+/**
+ * @file In-memory adapters for the `user-management` repo ports.
+ *
+ * Purpose:
+ * Test/dev implementations of the nine identity repo ports. Mirrors the exact
+ * style of `src/features/post/repo.memory.ts` / `src/members/repo.memory.ts`:
+ * constructor takes seed rows, methods filter/mutate an internal array. No
+ * business rules live here — that belongs to `authorize.ts`/`auth-service.ts`/
+ * `seed.ts`.
+ *
+ * Architectural role:
+ * The only adapter this pass — a SQLite adapter is a later step (see
+ * `ports.ts` header and `server/deps.ts` comments), matching the disclosed
+ * precedent of members/navigation/integrations/analytics.
+ */
+/** Snapshot seam used only by the memory transaction adapter; no business rules live here. */
+export declare abstract class InMemoryIdentityRows<Row> {
+    protected rows: Row[];
+    constructor(required: Record<string, never>, optional?: {
+        initialRows?: Row[];
+    });
+    /** Detached state so rollback also restores in-place changes such as session revocation. */
+    snapshotRows(required: Record<string, never>): Row[];
+    /** Restore a detached snapshot after the transaction rejects. */
+    restoreRows(required: {
+        rows: Row[];
+    }): void;
+}
+export declare class InMemoryPrincipalRepo extends InMemoryIdentityRows<PrincipalRecord> implements PrincipalRepoPort {
+    constructor(_required: Record<string, never>, { initialRows }?: {
+        initialRows?: PrincipalRecord[];
+    });
+    findById(required: {
+        workspaceId: string;
+        id: string;
+    }): Promise<PrincipalRecord | null>;
+    list(required: {
+        workspaceId: string;
+    }): Promise<PrincipalRecord[]>;
+    save(record: PrincipalRecord): Promise<void>;
+}
+export declare class InMemoryUserRepo extends InMemoryIdentityRows<UserRecord> implements UserRepoPort {
+    constructor(_required: Record<string, never>, { initialRows }?: {
+        initialRows?: UserRecord[];
+    });
+    findByPrincipalId(required: {
+        workspaceId: string;
+        principalId: string;
+    }): Promise<UserRecord | null>;
+    findByUsername(required: {
+        workspaceId: string;
+        username: string;
+    }): Promise<UserRecord | null>;
+    list(required: {
+        workspaceId: string;
+    }): Promise<UserRecord[]>;
+    save(record: UserRecord): Promise<void>;
+}
+export declare class InMemorySessionRepo extends InMemoryIdentityRows<SessionRecord> implements SessionRepoPort {
+    constructor(_required: Record<string, never>, { initialRows }?: {
+        initialRows?: SessionRecord[];
+    });
+    findById(required: {
+        workspaceId: string;
+        id: string;
+    }): Promise<SessionRecord | null>;
+    findByTokenHash(required: {
+        workspaceId: string;
+        tokenHash: string;
+    }): Promise<SessionRecord | null>;
+    save(record: SessionRecord): Promise<void>;
+    revoke(required: {
+        workspaceId: string;
+        id: string;
+        revokedAt: string;
+    }): Promise<void>;
+    listByPrincipalId(required: {
+        workspaceId: string;
+        principalId: string;
+    }): Promise<SessionRecord[]>;
+}
+export declare class InMemoryRoleRepo extends InMemoryIdentityRows<RoleRecord> implements RoleRepoPort {
+    constructor(_required: Record<string, never>, { initialRows }?: {
+        initialRows?: RoleRecord[];
+    });
+    findById(required: {
+        workspaceId: string;
+        id: string;
+    }): Promise<RoleRecord | null>;
+    findByName(required: {
+        workspaceId: string;
+        name: string;
+    }): Promise<RoleRecord | null>;
+    list(required: {
+        workspaceId: string;
+    }): Promise<RoleRecord[]>;
+    save(record: RoleRecord): Promise<void>;
+    delete(required: {
+        workspaceId: string;
+        id: string;
+    }): Promise<void>;
+}
+export declare class InMemoryPolicyRepo extends InMemoryIdentityRows<PolicyRecord> implements PolicyRepoPort {
+    constructor(_required: Record<string, never>, { initialRows }?: {
+        initialRows?: PolicyRecord[];
+    });
+    findById(required: {
+        workspaceId: string;
+        id: string;
+    }): Promise<PolicyRecord | null>;
+    findByName(required: {
+        workspaceId: string;
+        name: string;
+    }): Promise<PolicyRecord | null>;
+    list(required: {
+        workspaceId: string;
+    }): Promise<PolicyRecord[]>;
+    save(record: PolicyRecord): Promise<void>;
+    delete(required: {
+        workspaceId: string;
+        id: string;
+    }): Promise<void>;
+}
+export declare class InMemoryPolicyPermissionRepo extends InMemoryIdentityRows<PolicyPermissionRecord> implements PolicyPermissionRepoPort {
+    constructor(_required: Record<string, never>, { initialRows }?: {
+        initialRows?: PolicyPermissionRecord[];
+    });
+    listByPolicyId(required: {
+        workspaceId: string;
+        policyId: string;
+    }): Promise<PolicyPermissionRecord[]>;
+    save(record: PolicyPermissionRecord): Promise<void>;
+    deleteByPolicyId(required: {
+        workspaceId: string;
+        policyId: string;
+    }): Promise<void>;
+    delete(required: {
+        workspaceId: string;
+        id: string;
+    }): Promise<void>;
+}
+export declare class InMemoryRolePolicyRepo extends InMemoryIdentityRows<RolePolicyRecord> implements RolePolicyRepoPort {
+    constructor(_required: Record<string, never>, { initialRows }?: {
+        initialRows?: RolePolicyRecord[];
+    });
+    listByRoleId(required: {
+        workspaceId: string;
+        roleId: string;
+    }): Promise<RolePolicyRecord[]>;
+    listByPolicyId(required: {
+        workspaceId: string;
+        policyId: string;
+    }): Promise<RolePolicyRecord[]>;
+    save(record: RolePolicyRecord): Promise<void>;
+}
+export declare class InMemoryPrincipalRoleRepo extends InMemoryIdentityRows<PrincipalRoleRecord> implements PrincipalRoleRepoPort {
+    constructor(_required: Record<string, never>, { initialRows }?: {
+        initialRows?: PrincipalRoleRecord[];
+    });
+    listByPrincipalId(required: {
+        workspaceId: string;
+        principalId: string;
+    }): Promise<PrincipalRoleRecord[]>;
+    listByRoleId(required: {
+        workspaceId: string;
+        roleId: string;
+    }): Promise<PrincipalRoleRecord[]>;
+    save(record: PrincipalRoleRecord): Promise<void>;
+}
+export declare class InMemoryPrincipalPolicyRepo extends InMemoryIdentityRows<PrincipalPolicyRecord> implements PrincipalPolicyRepoPort {
+    constructor(_required: Record<string, never>, { initialRows }?: {
+        initialRows?: PrincipalPolicyRecord[];
+    });
+    listByPrincipalId(required: {
+        workspaceId: string;
+        principalId: string;
+    }): Promise<PrincipalPolicyRecord[]>;
+    listByPolicyId(required: {
+        workspaceId: string;
+        policyId: string;
+    }): Promise<PrincipalPolicyRecord[]>;
+    save(record: PrincipalPolicyRecord): Promise<void>;
+}
+//# sourceMappingURL=repo.memory.d.ts.map