@jini-ai/user-management 0.2.0

package/dist/server/agent-tools.d.ts

@@ -0,0 +1,88 @@
+import type { AgentToolDefinition as KernelAgentToolDefinition } from "@jini-ai/core";
+/**
+ * @file The identity (users/roles) agent-tool catalog — this domain's instance of the
+ * per-domain `agent-tools.ts` convention already used by `features/content-types`,
+ * `features/database`, and `features/recovery`.
+ *
+ * Purpose:
+ * A static, in-process catalog describing every agent-callable identity tool and the permission
+ * each one carries. `assistant/tool-registrations.ts` maps these entries onto handlers that call
+ * `grant-service.ts` / `admin-crud-service.ts` — the SAME functions the human admin routes under
+ * `server/routes/admin/users/` call. There is deliberately no path from a tool to the database
+ * that skips those functions, because they are where the domain's authorization gates live.
+ *
+ * WHAT THIS CATALOG DELIBERATELY OMITS, and why (identity is the escalation-dense
+ * surface, so the omissions are part of the design rather than a backlog):
+ *
+ * - `resetUserPassword`. The one identity transition that sets a credential on
+ * an account the caller does not own, and — unlike `ASSIGN_ROLE`/`ATTACH_POLICY` — it carries
+ * NO grant-authority clamp. A `user.manage` holder may reset the OWNER's password and
+ * then authenticate as owner, so it is a full account-takeover primitive rather than a
+ * permission grant. An assistant is reachable by prompt injection through ordinary operator
+ * content (a form submission, a comment) in a way a human clicking the admin button is not.
+ * Left human-UI-only, mirroring `features/content-types/agent-tools.ts`'s reasoning for never
+ * exposing the destructive-cleanup confirm step to an agent.
+ * - `writePolicyPermission`. This is the one policy transition still
+ * deliberately excluded, and on different grounds than the five wired below: unlike
+ * `identity_role_assign`/`identity_policy_attach`, which each confer whatever a role/policy
+ * ALREADY carries onto exactly one named target principal, `writePolicyPermission` MUTATES a
+ * shared, reusable `PolicyRecord` in place — and any non-built-in, non-frozen policy can
+ * already be attached to an arbitrary number of OTHER users via `identity_policy_attach` (or to
+ * roles via the seed-only `role_policies` table) before this call happens. The clamp
+ * (`assertGrantClamp`) still bounds WHAT the caller can add — only a permission it itself holds
+ * unconstrained — but it says nothing about WHO ends up holding it: every principal already
+ * attached to that policy inherits the new permission the instant it is written, invisibly to
+ * whoever asked for the one change. That is a materially different blast-radius shape than the
+ * single-target primitives this catalog does wire (see the tool descriptions below), and exactly
+ * the "grant that ripples to principals never named in the call" class this pass's directive
+ * asks to be excluded and explained rather than wired reflexively. Left human-UI-only, where
+ * the operator Roles screen's "Add permission" control still lives.
+ *
+ * Every OTHER policy transition (`identity_policy_list`, `identity_policy_create`,
+ * `identity_policy_update`, `identity_policy_delete`, `identity_policy_attach`) IS wired below,
+ * mirroring the risk profile this catalog already accepted for the equivalent role transitions
+ * (`identity_role_list`/`identity_role_create`/`identity_role_rename`/`identity_role_delete`/
+ * `identity_role_assign`) — see each entry's own description for why its shape matches its role
+ * counterpart exactly.
+ *
+ * - Role REVOCATION. Not a choice: no such operation exists anywhere in this codebase.
+ * `PrincipalRoleRepoPort` (`ports.ts`) declares `listByPrincipalId`, `save`, and `listByRoleId`
+ * — there is no `delete`, and no service function unassigns a role. A tool cannot be written
+ * against an operation the domain does not have, and adding a repo-level delete here to
+ * manufacture one would be exactly the "skip the service layer" failure this work exists to
+ * close. The same is true of "detach a policy from a principal" — `PrincipalPolicyRepoPort`
+ * has no delete either, so `identity_policy_attach` is one-directional exactly like
+ * `identity_role_assign`.
+ *
+ * Architectural role:
+ * `user-management` library declaration only. Performs no I/O and no enforcement — `authorize` and each
+ * service function's own caller-permission gate enforce at call time. The kernel supplies the
+ * structural catalog contract; this domain only requires inputSchema for every wired tool,
+ * so a low-level library never acquires a dependency on a host feature module.
+ * See docs/decisions/DR-002-grant-authority-and-admin-safety.md.
+ *
+ * The permission the tool's underlying service function gates on.
+ *
+ * `orPermission` is present where the service accepts an OR: listing users, and updating one's
+ * own email (other operator targets require `user.manage`). Recording only the first would make this catalog quietly
+ * disagree with the code it describes; `__tests__/agent-tools.authorization.test.ts` derives its
+ * expected permission set from BOTH fields, so an undeclared OR fails the suite.
+ *
+ * JSON Schema for this tool's `input`, published to the model via `ToolDescriptor.inputSchema`
+ * AND interpreted as the enforcing boundary parser by `agent-tool-input.ts`.
+ *
+ * Required even though the kernel permits omission: every entry here is
+ * wired, so there is no unwired entry whose input shape is undesigned.
+ */
+export type IdentityAgentToolDefinition = KernelAgentToolDefinition & {
+    inputSchema: Readonly<Record<string, unknown>>;
+};
+/**
+ * The identity domain's fixed agent-tool catalog.
+ *
+ * Ordered read-tools-first because that is the order a correct multi-step call chain uses: a model
+ * cannot assign a role without a `roleId`, and the only way to learn one for an EXISTING role
+ * (including the four seeded built-ins) is `identity_role_list`.
+ */
+export declare const identityAgentToolCatalog: IdentityAgentToolDefinition[];
+//# sourceMappingURL=agent-tools.d.ts.map

package/dist/server/agent-tools.js

@@ -0,0 +1,229 @@
+/** A workspace-scoped principal id, as returned by `identity_user_list` or `identity_user_create`. */
+const PRINCIPAL_ID_SCHEMA = {
+    type: "string",
+    minLength: 1,
+    description: "The user's principalId. Get it from identity_user_list, or from identity_user_create's result.",
+};
+/** A workspace-scoped role id, as returned by `identity_role_list` or `identity_role_create`. */
+const ROLE_ID_SCHEMA = {
+    type: "string",
+    minLength: 1,
+    description: "The role's id. Get it from identity_role_list, or from identity_role_create's result.",
+};
+/** A workspace-scoped policy id, as returned by `identity_policy_list` or `identity_policy_create`. */
+const POLICY_ID_SCHEMA = {
+    type: "string",
+    minLength: 1,
+    description: "The policy's id. Get it from identity_policy_list, or from identity_policy_create's result.",
+};
+/** A required, non-blank human-authored name. `minLength` is published because the service
+ * functions reject a blank/whitespace-only name — leaving it unstated would show the model a
+ * contract wider than the one enforced. */
+const REQUIRED_NAME_SCHEMA = {
+    type: "string",
+    minLength: 1,
+    description: "Human-readable name. Must not be blank or whitespace-only.",
+};
+/** The input shape of the three read tools — they take no arguments at all. */
+const NO_INPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: [],
+    properties: {},
+};
+/** `{principalId}` — shared by the two principal-status transitions, which take exactly that. */
+const PRINCIPAL_ONLY_INPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["principalId"],
+    properties: { principalId: PRINCIPAL_ID_SCHEMA },
+};
+/**
+ * The identity domain's fixed agent-tool catalog.
+ *
+ * Ordered read-tools-first because that is the order a correct multi-step call chain uses: a model
+ * cannot assign a role without a `roleId`, and the only way to learn one for an EXISTING role
+ * (including the four seeded built-ins) is `identity_role_list`.
+ */
+export const identityAgentToolCatalog = [
+    {
+        name: "identity_user_list",
+        description: "Lists the workspace's human operator users with their principalId, username, status, and assigned role ids. Read-only. Call this to find a user's principalId before updating, disabling, enabling, or assigning a role to them. There is no password-reset tool. The owner resets a user's password from the Users screen in the admin (Reset password).",
+        sideEffects: "none",
+        authorization: { permission: "user.manage", orPermission: "member.manage" },
+        inputSchema: NO_INPUT_SCHEMA,
+    },
+    {
+        name: "identity_role_list",
+        description: "Lists the workspace's roles (the four built-ins plus any custom ones) with their id, name, and isBuiltin flag. Read-only. Call this to find a roleId before assigning, renaming, or deleting a role.",
+        sideEffects: "none",
+        authorization: { permission: "role.manage" },
+        inputSchema: NO_INPUT_SCHEMA,
+    },
+    {
+        name: "identity_policy_list",
+        description: "Lists the workspace's policies (built-ins plus any custom ones) with their id, name, description, isBuiltin, and isFrozen flags. Read-only. Call this to find a policyId before renaming, deleting, or attaching a policy.",
+        sideEffects: "none",
+        authorization: { permission: "role.manage" },
+        inputSchema: NO_INPUT_SCHEMA,
+    },
+    {
+        name: "identity_user_create",
+        description: "Creates a new human operator user, minting a new principal and its credential row together. The new user starts with NO roles and therefore no permissions — grant access afterwards with identity_role_assign. Fails if the username is already taken.",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "user.manage" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["username", "password"],
+            properties: {
+                username: {
+                    type: "string",
+                    minLength: 1,
+                    description: "Login name. Stored lowercased and Unicode-NFC-normalized, and unique per workspace on that normalized form.",
+                },
+                password: {
+                    type: "string",
+                    minLength: 1,
+                    description: "Initial password. Hashed with argon2id before storage; never stored or returned in plaintext.",
+                },
+                email: { type: "string", description: "Optional contact email." },
+            },
+        },
+    },
+    {
+        name: "identity_user_update_email",
+        description: "Sets or clears an existing user's email address. Requires user.manage for other operator users; member.manage permits only editing your own email. Only an owner may edit an owner account. Omitting 'email' (or passing an empty string) CLEARS the stored value rather than leaving it unchanged. Username and password are not editable through this tool. There is no password-reset tool. The owner resets a user's password from the Users screen in the admin (Reset password).",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "user.manage", orPermission: "member.manage" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["principalId"],
+            properties: {
+                principalId: PRINCIPAL_ID_SCHEMA,
+                email: { type: "string", description: "The new email. Omit it or pass an empty string to clear the stored value." },
+            },
+        },
+    },
+    {
+        name: "identity_user_disable",
+        description: "Disables a user, revoking their access. Principals are never hard-deleted because the audit trail references them, so this is how a user is removed. Refuses to disable the seeded owner, and refuses any disable that would leave the workspace with no active owner. Already-disabled is a no-op.",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "user.manage" },
+        inputSchema: PRINCIPAL_ONLY_INPUT_SCHEMA,
+    },
+    {
+        name: "identity_user_enable",
+        description: "Re-enables a previously disabled human user. Already-active is a no-op. Only kind='user' principals can be enabled this way.",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "user.manage" },
+        inputSchema: PRINCIPAL_ONLY_INPUT_SCHEMA,
+    },
+    {
+        name: "identity_role_create",
+        description: "Creates a new custom role. The role starts with no policies attached and therefore confers no permissions until one is attached, which is not an agent-callable operation.",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "role.manage" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["name"],
+            properties: { name: REQUIRED_NAME_SCHEMA },
+        },
+    },
+    {
+        name: "identity_role_assign",
+        description: "Assigns an existing role to an existing user. This is the step that actually grants permissions. The caller can only confer permissions it already holds itself unconstrained, so assigning a role more powerful than the caller's own is refused. There is no tool to remove a role from a user, and no unassign operation exists anywhere in this system yet; tell the owner rather than trying another tool.",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "role.manage" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["principalId", "roleId"],
+            properties: { principalId: PRINCIPAL_ID_SCHEMA, roleId: ROLE_ID_SCHEMA },
+        },
+    },
+    {
+        name: "identity_role_rename",
+        description: "Renames a custom role. Built-in roles cannot be renamed — relabelling 'viewer' to read as trusted is a social-engineering variant of privilege escalation, so it is refused.",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "role.manage" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["roleId", "name"],
+            properties: { roleId: ROLE_ID_SCHEMA, name: REQUIRED_NAME_SCHEMA },
+        },
+    },
+    {
+        name: "identity_role_delete",
+        description: "Deletes a custom role. Built-in roles cannot be deleted. A role still assigned to at least one user is refused — this system has no unassign operation, so a role in use cannot be removed at all.",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "role.manage" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["roleId"],
+            properties: { roleId: ROLE_ID_SCHEMA },
+        },
+    },
+    {
+        name: "identity_policy_create",
+        description: "Creates a new custom policy. The policy starts with no permissions and therefore confers none until permissions are added, which is not an agent-callable operation — identity_policy_write_permission is deliberately not wired (see this file's own header comment). Attaching a freshly created, still-empty policy to anyone is a no-op.",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "role.manage" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["name"],
+            properties: {
+                name: REQUIRED_NAME_SCHEMA,
+                description: { type: "string", description: "Optional human-readable description." },
+            },
+        },
+    },
+    {
+        name: "identity_policy_update",
+        description: "Renames and/or re-describes a custom policy. Built-in and frozen policies are refused. At least one of 'name'/'description' must be supplied.",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "role.manage" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["policyId"],
+            properties: {
+                policyId: POLICY_ID_SCHEMA,
+                name: { type: "string", minLength: 1, description: "New name. Omit to leave unchanged." },
+                description: { type: "string", description: "New description. Omit to leave unchanged." },
+            },
+        },
+    },
+    {
+        name: "identity_policy_delete",
+        description: "Deletes a custom policy. Built-in and frozen policies cannot be deleted. A policy still referenced by at least one role or attached to at least one user is refused — deletion fails safe (it only ever removes access, never orphans a reference) exactly like identity_role_delete.",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "role.manage" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["policyId"],
+            properties: { policyId: POLICY_ID_SCHEMA },
+        },
+    },
+    {
+        name: "identity_policy_attach",
+        description: 
+        // See docs/decisions/DR-002-grant-authority-and-admin-safety.md for the invariant behind this refusal; keep external identifiers out of caller-facing messages.
+        "Attaches an existing policy directly to an existing user, granting every permission the policy carries. This is the direct-grant counterpart to identity_role_assign, targets exactly one named user per call, and carries the identical grant-authority clamp: the caller can only confer permissions it already holds itself unconstrained, so attaching a policy more powerful than the caller's own is refused. There is no detach operation.",
+        sideEffects: "mutates-durable-state",
+        authorization: { permission: "role.manage" },
+        inputSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["principalId", "policyId"],
+            properties: { principalId: PRINCIPAL_ID_SCHEMA, policyId: POLICY_ID_SCHEMA },
+        },
+    },
+];
+//# sourceMappingURL=agent-tools.js.map

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

@@ -0,0 +1,107 @@
+import { type UserManagementMessages } from "./messages.js";
+import type { SessionTokenPort } from "../core/runtime-ports.js";
+import type { Clock, IdGenerator, ISODateTime, UUID } from "@jini-ai/core/primitives";
+import type { IdentityRepos, PasswordHasherPort } from "../core/ports.js";
+import { type PrincipalRecord, type SessionRecord } from "../core/types.js";
+export interface AuthServiceDeps {
+    repos: IdentityRepos;
+    hasher: PasswordHasherPort;
+    clock: Clock;
+    idGen: IdGenerator;
+    tokens: SessionTokenPort;
+}
+/**
+ * Mint and persist a session for a principal the caller has ALREADY identified by some means
+ * other than this function (password verification in `login()` below, or a caller-specific proof
+ * such as a loopback-only single-use boot token). Factored out of `login()`'s former inline
+ * session-construction block (2026-09-06) so both paths share one minter — a host with no
+ * password to verify no longer has to hand-roll its own token hashing (and risk drifting from
+ * this file's private `hashToken`) just to mint a session for a principal it has already proven
+ * by other means.
+ *
+ * @complexity O(1) — one session write.
+ * @overallScore 100
+ */
+export declare function createSessionForPrincipal(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        principalId: UUID;
+    };
+}, optional?: {
+    ip?: string | undefined;
+    userAgent?: string | undefined;
+    sessionTtlMs?: number | undefined;
+    messages?: UserManagementMessages | undefined;
+}): Promise<{
+    session: SessionRecord;
+    rawToken: string;
+}>;
+/**
+ * Verify `username`+`password` for an `active` principal and mint a session
+ * Constant-shaped failure: a nonexistent username, a
+ * disabled principal, and a wrong password are all `AuthInvalidCredentialsError`
+ * with the same message — no user-enumeration signal.
+ *
+ * @complexity O(1) — one username lookup, one principal lookup, one hash
+ * verify, one session write (via `createSessionForPrincipal`), one `lastLoginAt` write.
+ * @overallScore 100
+ * See docs/decisions/DR-001-identity-and-session-boundary.md.
+ */
+export declare function login(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        username: string;
+        password: string;
+    };
+}, optional?: {
+    ip?: string;
+    userAgent?: string;
+    sessionTtlMs?: number;
+    messages?: UserManagementMessages;
+}): Promise<{
+    principal: PrincipalRecord;
+    session: SessionRecord;
+    rawToken: string;
+}>;
+/**
+ * Resolve a session cookie's raw token to its principal, applying every
+ * fail-closed check server-side : unknown
+ * token, revoked, past absolute `expiresAt`, or a disabled bound principal
+ * all resolve to `null` (the caller maps that to 401 `UNAUTHENTICATED` and
+ * never reaches `authorize`).
+ *
+ * @complexity O(1) — one token-hash lookup, one principal lookup.
+ * @overallScore 100
+ * See docs/decisions/DR-001-identity-and-session-boundary.md.
+ */
+export declare function validateSession(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        rawToken: string;
+    };
+}, optional?: {
+    nowIso?: ISODateTime;
+}): Promise<{
+    principal: PrincipalRecord;
+    session: SessionRecord;
+} | null>;
+/** Revoke the session bound to `rawToken`. Idempotent — already-revoked/unknown is a no-op. */
+export declare function logout(required: {
+    deps: AuthServiceDeps;
+    input: {
+        workspaceId: UUID;
+        rawToken: string;
+    };
+}): Promise<void>;
+/** The introspection surface for `AUTH_ME` : dotted permission strings, `["*"]` for owner. See docs/decisions/DR-001-identity-and-session-boundary.md. */
+export declare function getEffectivePermissions(required: {
+    deps: IdentityRepos;
+    input: {
+        workspaceId: UUID;
+        principalId: UUID;
+    };
+}): Promise<string[]>;
+//# sourceMappingURL=auth-service.d.ts.map

package/dist/server/auth-service.js

@@ -0,0 +1,170 @@
+import { defaultUserManagementMessages } from "./messages.js";
+import { nowIso as kernelNowIso } from "@jini-ai/core/primitives";
+import { resolveEffectivePermissions } from "./authorize.js";
+import { AuthInvalidCredentialsError } from "../core/types.js";
+import { normalizeUsername } from "./username.js";
+/**
+ * @file Login / logout / session validation (state.spec `LOGIN`/`LOGOUT`).
+ *
+ * Purpose:
+ * The credential-verification + session-lifecycle surface `middleware/dev-auth.ts`
+ * wires into HTTP. Session tokens are hashed with SHA-256 before storage — the
+ * same technique `members/write-service.ts` uses for magic-link/member-session
+ * tokens (: the raw token is never persisted). Password verification is
+ * argon2id (`hasher.ts`), never a raw comparison.
+ *
+ * `createSessionForPrincipal` (2026-09-06) is the one session minter; `login` calls it after
+ * verifying credentials, and a host that identifies a principal by some other means (e.g. a
+ * loopback-only single-use boot token, which has nothing to verify a password against) calls it
+ * directly instead of re-implementing session construction. Before this export existed, a
+ * downstream host had duplicated this file's private `hashToken` byte-for-byte because
+ * `login` was the only minter and hard-requires a password — this closes that fork.
+ *
+ * Architectural role:
+ * Ordinary core functions (like `updatePost`/`membersWriteService`), not a
+ * port — session/credential logic has one implementation.
+ * See docs/decisions/DR-001-identity-and-session-boundary.md.
+ */
+/** /behavior.spec §4: absolute session lifetime, fixed at creation; defaults to 30 days and is host-configurable. See docs/decisions/DR-001-identity-and-session-boundary.md. */
+const DEFAULT_SESSION_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+function isoPlusMs(nowIso, ms) {
+    return new Date(new Date(nowIso).getTime() + ms).toISOString();
+}
+/**
+ * Mint and persist a session for a principal the caller has ALREADY identified by some means
+ * other than this function (password verification in `login()` below, or a caller-specific proof
+ * such as a loopback-only single-use boot token). Factored out of `login()`'s former inline
+ * session-construction block (2026-09-06) so both paths share one minter — a host with no
+ * password to verify no longer has to hand-roll its own token hashing (and risk drifting from
+ * this file's private `hashToken`) just to mint a session for a principal it has already proven
+ * by other means.
+ *
+ * @complexity O(1) — one session write.
+ * @overallScore 100
+ */
+export async function createSessionForPrincipal(required, optional = {}) {
+    const { deps } = required;
+    const input = { ...required.input, ...optional };
+    const nowIso = kernelNowIso({ clock: deps.clock });
+    const sessionTtlMs = optional.sessionTtlMs ?? DEFAULT_SESSION_TTL_MS;
+    if (!Number.isFinite(sessionTtlMs) || sessionTtlMs <= 0)
+        throw new RangeError((optional.messages ?? defaultUserManagementMessages).invalidSessionTtl);
+    const rawToken = deps.tokens.newToken({});
+    const session = {
+        id: deps.idGen.newId(),
+        workspaceId: input.workspaceId,
+        principalId: input.principalId,
+        tokenHash: deps.tokens.hashToken({ rawToken }),
+        createdAt: nowIso,
+        expiresAt: isoPlusMs(nowIso, sessionTtlMs),
+        ip: input.ip,
+        userAgent: input.userAgent,
+    };
+    await deps.repos.sessions.save(session);
+    return { session, rawToken };
+}
+/**
+ * Verify `username`+`password` for an `active` principal and mint a session
+ * Constant-shaped failure: a nonexistent username, a
+ * disabled principal, and a wrong password are all `AuthInvalidCredentialsError`
+ * with the same message — no user-enumeration signal.
+ *
+ * @complexity O(1) — one username lookup, one principal lookup, one hash
+ * verify, one session write (via `createSessionForPrincipal`), one `lastLoginAt` write.
+ * @overallScore 100
+ * See docs/decisions/DR-001-identity-and-session-boundary.md.
+ */
+export async function login(required, optional = {}) {
+    const { deps } = required;
+    const input = { ...required.input, ...optional };
+    const username = normalizeUsername({ raw: input.username });
+    if (!username || !input.password) {
+        throw new AuthInvalidCredentialsError({ message: (optional.messages ?? defaultUserManagementMessages).invalidCredentials });
+    }
+    const userRow = await deps.repos.users.findByUsername({ workspaceId: input.workspaceId, username });
+    if (!userRow) {
+        throw new AuthInvalidCredentialsError({ message: (optional.messages ?? defaultUserManagementMessages).invalidCredentials });
+    }
+    const principal = await deps.repos.principals.findById({
+        workspaceId: input.workspaceId,
+        id: userRow.principalId,
+    });
+    if (!principal || principal.status !== "active") {
+        throw new AuthInvalidCredentialsError({ message: (optional.messages ?? defaultUserManagementMessages).invalidCredentials });
+    }
+    const passwordOk = await deps.hasher.verify({ hash: userRow.passwordHash, password: input.password });
+    if (!passwordOk) {
+        throw new AuthInvalidCredentialsError({ message: (optional.messages ?? defaultUserManagementMessages).invalidCredentials });
+    }
+    const { session, rawToken } = await createSessionForPrincipal({ deps, input: { workspaceId: input.workspaceId, principalId: principal.id } }, { ip: input.ip, userAgent: input.userAgent, sessionTtlMs: optional.sessionTtlMs, messages: optional.messages });
+    // Reuses the session's own `createdAt` rather than a second `kernelNowIso({ clock: clock })` call — both are
+    // meant to be the same instant, and reading one avoids two clock reads ever disagreeing.
+    await deps.repos.users.save({ ...userRow, lastLoginAt: session.createdAt });
+    return { principal, session, rawToken };
+}
+/**
+ * Resolve a session cookie's raw token to its principal, applying every
+ * fail-closed check server-side : unknown
+ * token, revoked, past absolute `expiresAt`, or a disabled bound principal
+ * all resolve to `null` (the caller maps that to 401 `UNAUTHENTICATED` and
+ * never reaches `authorize`).
+ *
+ * @complexity O(1) — one token-hash lookup, one principal lookup.
+ * @overallScore 100
+ * See docs/decisions/DR-001-identity-and-session-boundary.md.
+ */
+export async function validateSession(required, optional = {}) {
+    const { deps } = required;
+    const input = { ...required.input, ...optional };
+    const nowIso = input.nowIso ?? kernelNowIso({ clock: deps.clock });
+    const session = await deps.repos.sessions.findByTokenHash({
+        workspaceId: input.workspaceId,
+        tokenHash: deps.tokens.hashToken({ rawToken: input.rawToken }),
+    });
+    if (!session)
+        return null;
+    if (session.revokedAt)
+        return null;
+    // past absolute expiry is treated as revoked, never reaching authorize. See docs/decisions/DR-001-identity-and-session-boundary.md.
+    if (session.expiresAt <= nowIso)
+        return null;
+    const principal = await deps.repos.principals.findById({
+        workspaceId: input.workspaceId,
+        id: session.principalId,
+    });
+    // a disabled principal's live session stops validating immediately. See docs/decisions/DR-001-identity-and-session-boundary.md.
+    if (!principal || principal.status !== "active")
+        return null;
+    return { principal, session };
+}
+/** Revoke the session bound to `rawToken`. Idempotent — already-revoked/unknown is a no-op. */
+export async function logout(required) {
+    const { deps, input } = required;
+    const session = await deps.repos.sessions.findByTokenHash({
+        workspaceId: input.workspaceId,
+        tokenHash: deps.tokens.hashToken({ rawToken: input.rawToken }),
+    });
+    if (!session || session.revokedAt)
+        return;
+    await deps.repos.sessions.revoke({
+        workspaceId: input.workspaceId,
+        id: session.id,
+        revokedAt: kernelNowIso({ clock: deps.clock }),
+    });
+}
+/** The introspection surface for `AUTH_ME` : dotted permission strings, `["*"]` for owner. See docs/decisions/DR-001-identity-and-session-boundary.md. */
+export async function getEffectivePermissions(required) {
+    const rows = await resolveEffectivePermissions({
+        deps: {
+            principals: required.deps.principals,
+            principalRoles: required.deps.principalRoles,
+            rolePolicies: required.deps.rolePolicies,
+            principalPolicies: required.deps.principalPolicies,
+            policyPermissions: required.deps.policyPermissions,
+        },
+        principalId: required.input.principalId,
+        workspaceId: required.input.workspaceId,
+    });
+    return [...new Set(rows.map((row) => row.permission))];
+}
+//# sourceMappingURL=auth-service.js.map