@imenam/mcp-organizer 0.0.0-stage → 1.0.1

package/dist/src/core/accounts.d.ts

@@ -0,0 +1,129 @@
+import type { Mutation, Store } from "./store.js";
+import { type AccessLink, type User } from "../../shared/schemas/entities.schema.js";
+import type { AccessLinkPurpose } from "../../shared/schemas/enums.schema.js";
+/** Durée d'une session sans activité. */
+export declare const SESSION_TTL_MS: number;
+/** Intervalle minimal entre deux prolongations d'une même session. */
+export declare const SESSION_REFRESH_INTERVAL_MS: number;
+/** Durée de validité d'un lien d'invitation ou de réinitialisation. */
+export declare const ACCESS_LINK_TTL_MS: number;
+export declare function hashPassword(password: string): Promise<string>;
+/** Vérifie un mot de passe ; un compte sans mot de passe et un hash illisible sont refusés. */
+export declare function verifyPassword(hash: string | null, password: string): Promise<boolean>;
+/** Jeton opaque de 32 octets, en base64url. */
+export declare function newToken(): string;
+/** Hash sha256 (hexadécimal) sous lequel un jeton est stocké. */
+export declare function hashToken(token: string): string;
+/** Adresse validée et normalisée, ou erreur explicite. */
+export declare function normalizeEmail(email: string): string;
+/** Nom affiché validé (non vide, longueur bornée), ou erreur explicite. */
+export declare function normalizeDisplayName(name: string): string;
+/**
+ * Rend un compte actif : nom affiché et mot de passe posés, espace personnel
+ * créé s'il manque. Les invitations en attente du compte restent en attente :
+ * il les accepte ou les refuse une fois connecté.
+ */
+export declare function activateAccount(tx: Mutation, user: User, input: {
+    displayName: string;
+    passwordHash: string;
+}): User;
+/** Accepte une invitation en attente pour le compte `userId`, qui rejoint l'espace. */
+export declare function joinInvitedSpace(tx: Mutation, userId: string, invitationId: string): void;
+/** Crée l'espace personnel d'un compte s'il n'en a pas. */
+export declare function ensurePersonalSpace(tx: Mutation, userId: string): void;
+export interface BootstrapResult {
+    /** `created` : compte créé ; `exists` : des comptes existent ; `missing` : aucun compte ni variable. */
+    outcome: "created" | "exists" | "missing";
+    message: string;
+}
+/**
+ * Crée le premier compte depuis les variables d'environnement, si et
+ * seulement si la table est vide. Une adresse et un mot de passe sans nom
+ * affiché sont refusés.
+ */
+export declare function bootstrapAdmin(store: Store, credentials: {
+    email?: string;
+    displayName?: string;
+    password?: string;
+}): Promise<BootstrapResult>;
+/** Compte à créer ou à réactiver. `displayName` est requis pour un compte qui n'en a pas encore. */
+export interface SetAccountInput {
+    email: string;
+    password: string;
+    displayName?: string;
+}
+/** Message d'un compte créé sans nom affiché. */
+export declare const DISPLAY_NAME_REQUIRED_MESSAGE = "Le nom affich\u00E9 du compte est requis.";
+/**
+ * Crée un compte actif, ou remplace le mot de passe d'un compte existant, qui
+ * redevient actif (et prend le nom affiché donné). Les sessions ouvertes du
+ * compte sont fermées.
+ */
+export declare function setAccount(store: Store, input: SetAccountInput): Promise<{
+    created: boolean;
+    user: User;
+}>;
+/** Change le nom affiché d'un compte. */
+export declare function updateDisplayName(store: Store, userId: string, displayName: string): User;
+/**
+ * Change le mot de passe d'un compte après vérification de l'ancien. Les
+ * autres sessions du compte sont fermées ; celle de `keepSessionToken` reste ouverte.
+ */
+export declare function changePassword(store: Store, userId: string, input: {
+    currentPassword: string;
+    newPassword: string;
+}, keepSessionToken: string | null): Promise<void>;
+/** Session ouverte : le jeton à placer dans le cookie et sa fin de validité. */
+export interface IssuedSession {
+    token: string;
+    expiresAt: string;
+}
+/** Ouvre une session pour `userId` dans la mutation en cours. */
+export declare function openSession(tx: Mutation, userId: string, now: Date): IssuedSession;
+/** Vérifie e-mail et mot de passe et ouvre une session. */
+export declare function login(store: Store, email: string, password: string, now?: Date): Promise<{
+    user: User;
+    session: IssuedSession;
+}>;
+/**
+ * Utilisateur d'une session valide, ou null. Une session expirée, ou d'un
+ * compte qui n'est plus actif, est supprimée. L'expiration glisse : une
+ * session utilisée est prolongée (au plus une fois par
+ * `SESSION_REFRESH_INTERVAL_MS`), et `refreshed` porte alors le cookie à renvoyer.
+ */
+export declare function authenticate(store: Store, token: string | null, now?: Date): {
+    user: User;
+    refreshed: IssuedSession | null;
+} | null;
+/** Ferme la session du jeton, si elle existe. */
+export declare function logout(store: Store, token: string | null): void;
+/** Lien émis : le jeton en clair, qui n'est montré qu'une fois. */
+export interface IssuedAccessLink {
+    token: string;
+    expiresAt: string;
+}
+/** Chemin de la GUI qui ouvre l'écran d'activation d'un lien. */
+export declare function accessLinkPath(token: string): string;
+/**
+ * Émet un lien pour un compte, dans la mutation en cours. Un lien
+ * d'invitation est rattaché à `invitationId` et remplace le lien précédent de
+ * cette invitation ; les liens des autres invitations restent valables.
+ */
+export declare function issueAccessLink(tx: Mutation, userId: string, purpose: AccessLinkPurpose, invitationId: string | null, now: Date): IssuedAccessLink;
+/** Lien valide et son compte ; sinon une erreur qui dit pourquoi le lien ne fonctionne pas. */
+export declare function resolveAccessLink(store: Store, token: string, now?: Date): {
+    link: AccessLink;
+    user: User;
+};
+/**
+ * Consomme un lien : nom affiché et mot de passe posés, compte activé (espace
+ * personnel créé), session ouverte. Un lien d'invitation accepte l'invitation
+ * qui l'a émis, et elle seule.
+ */
+export declare function redeemAccessLink(store: Store, token: string, input: {
+    displayName: string;
+    password: string;
+}, now?: Date): Promise<{
+    user: User;
+    session: IssuedSession;
+}>;

package/dist/src/core/accounts.js

@@ -0,0 +1,284 @@
+import { createHash, randomBytes } from "node:crypto";
+import argon2 from "argon2";
+import { InvariantError, NotFoundError, OrganizerError, UnauthorizedError } from "./errors.js";
+import { newId } from "./ids.js";
+import { DisplayNameSchema, MIN_PASSWORD_LENGTH } from "../../shared/schemas/api.schema.js";
+import { EmailSchema } from "../../shared/schemas/entities.schema.js";
+import { PERSONAL_KEY_PREFIX, PERSONAL_SPACE_NAME } from "../../shared/logic/spaces.js";
+import { NO_ACCOUNT_MESSAGE } from "../../shared/logic/first-account.js";
+/**
+ * Comptes, mots de passe, sessions et liens d'accès.
+ *
+ * Les comptes se créent sur invitation. Le premier compte vient des variables
+ * `ORGANIZER_ADMIN_EMAIL` / `ORGANIZER_ADMIN_NAME` / `ORGANIZER_ADMIN_PASSWORD` (au démarrage, si la
+ * table est vide) ou de la commande `--set-user`. Les mots de passe sont hachés
+ * en argon2id ; les jetons de session et de lien ne sont stockés que hachés
+ * (sha256).
+ */
+/**
+ * Paramètres argon2id (recommandation OWASP : 19 Mio, 2 passes, 1 fil), fixés
+ * explicitement pour qu'une mise à jour de la bibliothèque ne change pas le coût.
+ */
+const ARGON2_OPTIONS = {
+    type: argon2.argon2id,
+    memoryCost: 19_456,
+    timeCost: 2,
+    parallelism: 1,
+};
+/** Durée d'une session sans activité. */
+export const SESSION_TTL_MS = 14 * 24 * 60 * 60 * 1000;
+/** Intervalle minimal entre deux prolongations d'une même session. */
+export const SESSION_REFRESH_INTERVAL_MS = 60 * 60 * 1000;
+/** Durée de validité d'un lien d'invitation ou de réinitialisation. */
+export const ACCESS_LINK_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const BAD_CREDENTIALS_MESSAGE = "Adresse e-mail ou mot de passe incorrect.";
+export async function hashPassword(password) {
+    if (password.length < MIN_PASSWORD_LENGTH) {
+        throw new OrganizerError(`Le mot de passe doit faire au moins ${MIN_PASSWORD_LENGTH} caractères.`);
+    }
+    return argon2.hash(password, ARGON2_OPTIONS);
+}
+/** Vérifie un mot de passe ; un compte sans mot de passe et un hash illisible sont refusés. */
+export async function verifyPassword(hash, password) {
+    if (hash === null)
+        return false;
+    try {
+        return await argon2.verify(hash, password);
+    }
+    catch {
+        return false;
+    }
+}
+/** Hash d'un mot de passe arbitraire, vérifié quand l'adresse est inconnue pour garder un temps de réponse constant. */
+let decoyHash = null;
+function decoy() {
+    decoyHash ??= argon2.hash(randomBytes(16).toString("hex"), ARGON2_OPTIONS);
+    return decoyHash;
+}
+/** Jeton opaque de 32 octets, en base64url. */
+export function newToken() {
+    return randomBytes(32).toString("base64url");
+}
+/** Hash sha256 (hexadécimal) sous lequel un jeton est stocké. */
+export function hashToken(token) {
+    return createHash("sha256").update(token, "utf8").digest("hex");
+}
+/** Adresse validée et normalisée, ou erreur explicite. */
+export function normalizeEmail(email) {
+    const parsed = EmailSchema.safeParse(email);
+    if (!parsed.success)
+        throw new OrganizerError(`Adresse e-mail invalide : « ${email} ».`);
+    return parsed.data;
+}
+/** Nom affiché validé (non vide, longueur bornée), ou erreur explicite. */
+export function normalizeDisplayName(name) {
+    const parsed = DisplayNameSchema.safeParse(name);
+    if (!parsed.success)
+        throw new OrganizerError(parsed.error.issues.map((issue) => issue.message).join(" "));
+    return parsed.data;
+}
+// --- Activation ---------------------------------------------------------------
+/**
+ * Rend un compte actif : nom affiché et mot de passe posés, espace personnel
+ * créé s'il manque. Les invitations en attente du compte restent en attente :
+ * il les accepte ou les refuse une fois connecté.
+ */
+export function activateAccount(tx, user, input) {
+    const active = tx.updateUser(user.id, { displayName: input.displayName, passwordHash: input.passwordHash, status: "active" });
+    ensurePersonalSpace(tx, user.id);
+    return active;
+}
+/** Accepte une invitation en attente pour le compte `userId`, qui rejoint l'espace. */
+export function joinInvitedSpace(tx, userId, invitationId) {
+    const invitation = tx.acceptInvitation(invitationId);
+    if (!tx.store.isMember(invitation.spaceId, userId))
+        tx.addMember(invitation.spaceId, userId);
+}
+/** Crée l'espace personnel d'un compte s'il n'en a pas. */
+export function ensurePersonalSpace(tx, userId) {
+    if (tx.store.findPersonalSpace(userId))
+        return;
+    tx.createSpace({ name: PERSONAL_SPACE_NAME, kind: "personal", ownerId: userId, keyPrefix: PERSONAL_KEY_PREFIX });
+}
+/**
+ * Crée le premier compte depuis les variables d'environnement, si et
+ * seulement si la table est vide. Une adresse et un mot de passe sans nom
+ * affiché sont refusés.
+ */
+export async function bootstrapAdmin(store, credentials) {
+    const count = store.countUsers();
+    if (count > 0)
+        return { outcome: "exists", message: `${count} account(s) in the database.` };
+    const email = credentials.email?.trim();
+    const password = credentials.password;
+    if (!email || !password) {
+        return {
+            outcome: "missing",
+            message: "No account exists: the GUI refuses every login. Create the first one with ORGANIZER_ADMIN_EMAIL, ORGANIZER_ADMIN_NAME and ORGANIZER_ADMIN_PASSWORD, " +
+                'or with: node dist/src/index.js --set-user <email> --name="First Last" (cloned site) or npx -y @imenam/mcp-organizer --set-user <email> --name="First Last" (npm package)',
+        };
+    }
+    const displayName = credentials.displayName?.trim();
+    if (!displayName)
+        throw new OrganizerError("ORGANIZER_ADMIN_NAME is not set: give the display name of the first account (for example: Matthieu Pin).");
+    const result = await setAccount(store, { email, password, displayName });
+    return { outcome: "created", message: `First account ${result.user.email} created from ORGANIZER_ADMIN_EMAIL / ORGANIZER_ADMIN_NAME / ORGANIZER_ADMIN_PASSWORD.` };
+}
+/** Message d'un compte créé sans nom affiché. */
+export const DISPLAY_NAME_REQUIRED_MESSAGE = "Le nom affiché du compte est requis.";
+/**
+ * Crée un compte actif, ou remplace le mot de passe d'un compte existant, qui
+ * redevient actif (et prend le nom affiché donné). Les sessions ouvertes du
+ * compte sont fermées.
+ */
+export async function setAccount(store, input) {
+    const normalized = normalizeEmail(input.email);
+    const displayName = input.displayName === undefined ? undefined : normalizeDisplayName(input.displayName);
+    const passwordHash = await hashPassword(input.password);
+    const userId = store.findUserByEmail(normalized)?.id ?? newId();
+    return store.mutate({ type: "user", userId }, (tx) => {
+        const existing = tx.store.findUserByEmail(normalized);
+        const name = displayName ?? existing?.displayName;
+        if (!name)
+            throw new OrganizerError(DISPLAY_NAME_REQUIRED_MESSAGE);
+        if (existing) {
+            const user = activateAccount(tx, existing, { displayName: name, passwordHash });
+            tx.deleteSessionsOf(user.id);
+            tx.discardUnusedAccessLinks(user.id);
+            return { created: false, user };
+        }
+        const created = tx.createUser({ id: userId, email: normalized, displayName: name, passwordHash, status: "active" });
+        ensurePersonalSpace(tx, created.id);
+        return { created: true, user: created };
+    });
+}
+// --- Profil ---------------------------------------------------------------------
+/** Change le nom affiché d'un compte. */
+export function updateDisplayName(store, userId, displayName) {
+    const name = normalizeDisplayName(displayName);
+    return store.mutate({ type: "user", userId }, (tx) => tx.updateUser(userId, { displayName: name }));
+}
+/**
+ * Change le mot de passe d'un compte après vérification de l'ancien. Les
+ * autres sessions du compte sont fermées ; celle de `keepSessionToken` reste ouverte.
+ */
+export async function changePassword(store, userId, input, keepSessionToken) {
+    const user = store.getUser(userId);
+    if (!(await verifyPassword(user.passwordHash, input.currentPassword)))
+        throw new OrganizerError("Le mot de passe actuel est incorrect.");
+    const passwordHash = await hashPassword(input.newPassword);
+    store.mutate({ type: "user", userId }, (tx) => {
+        tx.updateUser(userId, { passwordHash });
+        tx.deleteSessionsOf(userId, keepSessionToken === null ? null : hashToken(keepSessionToken));
+    });
+}
+/** Ouvre une session pour `userId` dans la mutation en cours. */
+export function openSession(tx, userId, now) {
+    const token = newToken();
+    const expiresAt = new Date(now.getTime() + SESSION_TTL_MS).toISOString();
+    tx.deleteExpiredSessions(now.toISOString());
+    tx.createSession({ idHash: hashToken(token), userId, createdAt: now.toISOString(), expiresAt });
+    return { token, expiresAt };
+}
+/** Vérifie e-mail et mot de passe et ouvre une session. */
+export async function login(store, email, password, now = new Date()) {
+    if (store.countUsers() === 0)
+        throw new UnauthorizedError(NO_ACCOUNT_MESSAGE);
+    const user = store.findUserByEmail(email);
+    if (!user || user.passwordHash === null) {
+        await verifyPassword(await decoy(), password);
+        throw new UnauthorizedError(BAD_CREDENTIALS_MESSAGE);
+    }
+    if (!(await verifyPassword(user.passwordHash, password)))
+        throw new UnauthorizedError(BAD_CREDENTIALS_MESSAGE);
+    if (user.status !== "active")
+        throw new UnauthorizedError("Ce compte n'est pas actif.");
+    const session = store.mutate({ type: "user", userId: user.id }, (tx) => openSession(tx, user.id, now));
+    return { user, session };
+}
+/**
+ * Utilisateur d'une session valide, ou null. Une session expirée, ou d'un
+ * compte qui n'est plus actif, est supprimée. L'expiration glisse : une
+ * session utilisée est prolongée (au plus une fois par
+ * `SESSION_REFRESH_INTERVAL_MS`), et `refreshed` porte alors le cookie à renvoyer.
+ */
+export function authenticate(store, token, now = new Date()) {
+    if (!token)
+        return null;
+    const idHash = hashToken(token);
+    const session = store.findSessionByHash(idHash);
+    if (!session)
+        return null;
+    const user = store.findUser(session.userId);
+    if (!user || user.status !== "active" || Date.parse(session.expiresAt) <= now.getTime()) {
+        store.mutate({ type: "user", userId: session.userId }, (tx) => tx.deleteSession(idHash));
+        return null;
+    }
+    const remaining = Date.parse(session.expiresAt) - now.getTime();
+    if (remaining > SESSION_TTL_MS - SESSION_REFRESH_INTERVAL_MS)
+        return { user, refreshed: null };
+    const expiresAt = new Date(now.getTime() + SESSION_TTL_MS).toISOString();
+    store.mutate({ type: "user", userId: user.id }, (tx) => tx.extendSession(idHash, expiresAt));
+    return { user, refreshed: { token, expiresAt } };
+}
+/** Ferme la session du jeton, si elle existe. */
+export function logout(store, token) {
+    if (!token)
+        return;
+    const session = store.findSessionByHash(hashToken(token));
+    if (!session)
+        return;
+    store.mutate({ type: "user", userId: session.userId }, (tx) => tx.deleteSession(session.idHash));
+}
+/** Chemin de la GUI qui ouvre l'écran d'activation d'un lien. */
+export function accessLinkPath(token) {
+    return `#/activation/${token}`;
+}
+/**
+ * Émet un lien pour un compte, dans la mutation en cours. Un lien
+ * d'invitation est rattaché à `invitationId` et remplace le lien précédent de
+ * cette invitation ; les liens des autres invitations restent valables.
+ */
+export function issueAccessLink(tx, userId, purpose, invitationId, now) {
+    const token = newToken();
+    const expiresAt = new Date(now.getTime() + ACCESS_LINK_TTL_MS).toISOString();
+    tx.createAccessLink({ userId, purpose, invitationId, tokenHash: hashToken(token), expiresAt });
+    return { token, expiresAt };
+}
+/** Lien valide et son compte ; sinon une erreur qui dit pourquoi le lien ne fonctionne pas. */
+export function resolveAccessLink(store, token, now = new Date()) {
+    const link = store.findAccessLinkByHash(hashToken(token));
+    if (!link) {
+        throw new NotFoundError("Ce lien n'est pas valide : il a été révoqué ou remplacé par un lien plus récent. Demandez un nouveau lien à la personne qui vous a invité.");
+    }
+    if (link.usedAt !== null)
+        throw new InvariantError("Ce lien a déjà été utilisé. Connectez-vous avec votre adresse e-mail et votre mot de passe.");
+    if (Date.parse(link.expiresAt) <= now.getTime()) {
+        throw new InvariantError("Ce lien a expiré. Demandez un nouveau lien à la personne qui vous a invité.");
+    }
+    const user = store.getUser(link.userId);
+    if (user.status === "disabled")
+        throw new InvariantError("Ce compte est désactivé.");
+    if (link.purpose === "invite" && user.status !== "invited") {
+        throw new InvariantError("Ce compte est déjà activé : connectez-vous avec votre adresse e-mail et votre mot de passe. L'invitation vous attend dans « Invitations reçues », dans le menu de l'espace.");
+    }
+    return { link, user };
+}
+/**
+ * Consomme un lien : nom affiché et mot de passe posés, compte activé (espace
+ * personnel créé), session ouverte. Un lien d'invitation accepte l'invitation
+ * qui l'a émis, et elle seule.
+ */
+export async function redeemAccessLink(store, token, input, now = new Date()) {
+    const { user: owner } = resolveAccessLink(store, token, now);
+    const passwordHash = await hashPassword(input.password);
+    return store.mutate({ type: "user", userId: owner.id }, (tx) => {
+        const { link, user } = resolveAccessLink(tx.store, token, now);
+        tx.markAccessLinkUsed(link.id);
+        const active = activateAccount(tx, user, { displayName: input.displayName, passwordHash });
+        if (link.invitationId !== null)
+            joinInvitedSpace(tx, user.id, link.invitationId);
+        tx.deleteSessionsOf(user.id);
+        return { user: active, session: openSession(tx, user.id, now) };
+    });
+}

package/dist/src/core/agent-tokens.d.ts

@@ -0,0 +1,31 @@
+import type { Store } from "./store.js";
+import type { AgentToken, Space, User } from "../../shared/schemas/entities.schema.js";
+import { type AgentTokenView, type CreateTokenRequest, type CreatedTokenResponse, type TokenListResponse, type TokenState } from "../../shared/schemas/tokens-api.schema.js";
+/** Nouveau jeton d'agent en clair. */
+export declare function generateAgentToken(): string;
+/** Hash sha256 (hexadécimal) d'un jeton. */
+export declare function hashAgentToken(token: string): string;
+/** État d'un jeton à l'instant `now` ; la révocation l'emporte sur l'expiration, l'expiration sur la perte d'accès. */
+export declare function tokenState(store: Store, token: AgentToken, now: Date): TokenState;
+/** Jetons de l'utilisateur : actifs d'abord, puis du plus récent au plus ancien. */
+export declare function listAgentTokens(store: Store, userId: string, now?: Date): TokenListResponse;
+/**
+ * Crée un jeton de l'utilisateur sur un espace dont il est membre ; renvoie
+ * sa valeur, montrée une seule fois, et l'entrée `.mcp.json` du mode MCP
+ * relié au site `publicUrl`.
+ */
+export declare function createAgentToken(store: Store, userId: string, input: CreateTokenRequest, publicUrl: string, now?: Date): CreatedTokenResponse;
+/** Révoque un jeton de l'utilisateur ; un jeton d'un autre est introuvable. */
+export declare function revokeAgentToken(store: Store, userId: string, tokenId: string, now?: Date): AgentTokenView;
+/** Jeton résolu par l'API agent : le jeton, son propriétaire et l'espace couvert. */
+export interface ResolvedAgentToken {
+    token: AgentToken;
+    user: User;
+    space: Space;
+}
+/**
+ * Résout le jeton présenté par un agent et note son usage. Un jeton absent,
+ * inconnu, révoqué ou expiré est refusé (401) ; un propriétaire inactif ou
+ * qui n'est plus membre de l'espace couvert aussi (403).
+ */
+export declare function resolveAgentToken(store: Store, raw: string | null, now?: Date): ResolvedAgentToken;

package/dist/src/core/agent-tokens.js

@@ -0,0 +1,120 @@
+import { createHash, randomBytes } from "node:crypto";
+import { ForbiddenError, NotFoundError, UnauthorizedError } from "./errors.js";
+import { requireMember } from "./spaces.js";
+import { buildAgentEntry, mcpJsonText } from "./mcp-entry.js";
+import { AGENT_TOKEN_PREFIX, } from "../../shared/schemas/tokens-api.schema.js";
+/**
+ * Jetons d'agent. Un utilisateur crée un jeton pour un espace dont il est
+ * membre ; le jeton (`org_` + 32 octets aléatoires en base64url) n'est
+ * montré qu'à sa création, seul son hash sha256 est stocké. À chaque appel
+ * de l'API agent, le jeton est résolu : non révoqué, non expiré, propriétaire
+ * actif et toujours membre de l'espace couvert. Quitter un espace, ou en être
+ * retiré, révoque les jetons du membre sur cet espace.
+ */
+/** Nombre de caractères aléatoires gardés dans le préfixe affiché d'un jeton. */
+const PREFIX_RANDOM_CHARS = 8;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const asUser = (userId) => ({ type: "user", userId });
+/** Nouveau jeton d'agent en clair. */
+export function generateAgentToken() {
+    return `${AGENT_TOKEN_PREFIX}${randomBytes(32).toString("base64url")}`;
+}
+/** Hash sha256 (hexadécimal) d'un jeton. */
+export function hashAgentToken(token) {
+    return createHash("sha256").update(token, "utf8").digest("hex");
+}
+/** État d'un jeton à l'instant `now` ; la révocation l'emporte sur l'expiration, l'expiration sur la perte d'accès. */
+export function tokenState(store, token, now) {
+    if (token.revokedAt !== null)
+        return "revoked";
+    if (token.expiresAt !== null && Date.parse(token.expiresAt) <= now.getTime())
+        return "expired";
+    const user = store.findUser(token.userId);
+    if (!user || user.status !== "active" || !store.isMember(token.spaceId, token.userId))
+        return "inactive";
+    return "active";
+}
+function tokenView(store, token, now) {
+    const space = store.getSpace(token.spaceId);
+    return {
+        id: token.id,
+        name: token.name,
+        prefix: token.prefix,
+        space: { id: space.id, name: space.name, kind: space.kind },
+        state: tokenState(store, token, now),
+        createdAt: token.createdAt,
+        lastUsedAt: token.lastUsedAt,
+        expiresAt: token.expiresAt,
+        revokedAt: token.revokedAt,
+    };
+}
+const STATE_ORDER = { active: 0, inactive: 1, expired: 2, revoked: 3 };
+/** Jetons de l'utilisateur : actifs d'abord, puis du plus récent au plus ancien. */
+export function listAgentTokens(store, userId, now = new Date()) {
+    const tokens = store.listAgentTokensOf(userId).map((token) => tokenView(store, token, now));
+    tokens.sort((a, b) => STATE_ORDER[a.state] - STATE_ORDER[b.state] || b.createdAt.localeCompare(a.createdAt));
+    return { tokens };
+}
+/**
+ * Crée un jeton de l'utilisateur sur un espace dont il est membre ; renvoie
+ * sa valeur, montrée une seule fois, et l'entrée `.mcp.json` du mode MCP
+ * relié au site `publicUrl`.
+ */
+export function createAgentToken(store, userId, input, publicUrl, now = new Date()) {
+    const value = generateAgentToken();
+    const token = store.mutate(asUser(userId), (tx) => {
+        requireMember(tx.store, input.spaceId, userId);
+        return tx.createAgentToken({
+            spaceId: input.spaceId,
+            name: input.name,
+            prefix: value.slice(0, AGENT_TOKEN_PREFIX.length + PREFIX_RANDOM_CHARS),
+            tokenHash: hashAgentToken(value),
+            expiresAt: input.expiresInDays === null ? null : new Date(now.getTime() + input.expiresInDays * DAY_MS).toISOString(),
+        });
+    });
+    return { token: tokenView(store, token, now), value, mcpJson: mcpJsonText(buildAgentEntry({ url: publicUrl, token: value })) };
+}
+/** Révoque un jeton de l'utilisateur ; un jeton d'un autre est introuvable. */
+export function revokeAgentToken(store, userId, tokenId, now = new Date()) {
+    const token = store.mutate(asUser(userId), (tx) => {
+        const found = tx.store.findAgentToken(tokenId);
+        if (!found || found.userId !== userId)
+            throw new NotFoundError("Jeton introuvable.");
+        return tx.revokeAgentToken(tokenId);
+    });
+    return tokenView(store, token, now);
+}
+/** Marche à suivre pour obtenir un jeton valide, rappelée dans les refus. */
+const NEW_TOKEN_HINT = "Create a token in the organizer web app (Paramètres > Agents) and set it as ORGANIZER_TOKEN.";
+/**
+ * Résout le jeton présenté par un agent et note son usage. Un jeton absent,
+ * inconnu, révoqué ou expiré est refusé (401) ; un propriétaire inactif ou
+ * qui n'est plus membre de l'espace couvert aussi (403).
+ */
+export function resolveAgentToken(store, raw, now = new Date()) {
+    if (raw === null || raw.trim() === "") {
+        throw new UnauthorizedError(`Missing agent token: send "Authorization: Bearer org_…". ${NEW_TOKEN_HINT}`);
+    }
+    const value = raw.trim();
+    if (!value.startsWith(AGENT_TOKEN_PREFIX))
+        throw new UnauthorizedError(`This is not an organizer agent token (they start with "${AGENT_TOKEN_PREFIX}"). ${NEW_TOKEN_HINT}`);
+    const token = store.findAgentTokenByHash(hashAgentToken(value));
+    if (!token)
+        throw new UnauthorizedError(`Unknown agent token. ${NEW_TOKEN_HINT}`);
+    if (token.revokedAt !== null) {
+        throw new UnauthorizedError(`Agent token "${token.name}" was revoked on ${token.revokedAt.slice(0, 10)}, by its owner or because its owner left or was removed from the space it covers. ${NEW_TOKEN_HINT}`);
+    }
+    if (token.expiresAt !== null && Date.parse(token.expiresAt) <= now.getTime()) {
+        throw new UnauthorizedError(`Agent token "${token.name}" expired on ${token.expiresAt.slice(0, 10)}. ${NEW_TOKEN_HINT}`);
+    }
+    const user = store.getUser(token.userId);
+    if (user.status !== "active")
+        throw new ForbiddenError(`The account that owns agent token "${token.name}" is not active: the token cannot be used.`);
+    const space = store.getSpace(token.spaceId);
+    if (!store.isMember(space.id, user.id)) {
+        throw new ForbiddenError(`The owner of agent token "${token.name}" is no longer a member of space "${space.name}": the token cannot be used. ${NEW_TOKEN_HINT}`);
+    }
+    const usedAt = now.toISOString();
+    store.mutate(asUser(user.id), (tx) => tx.recordAgentTokenUse(token.id, usedAt));
+    return { token: { ...token, lastUsedAt: usedAt }, user, space };
+}

package/dist/src/core/agent.d.ts

@@ -0,0 +1,71 @@
+import type { Actor, Mutation, Store } from "./store.js";
+import type { AgentRequest, Idea, Space, Task, TaskSnapshot, User } from "../../shared/schemas/entities.schema.js";
+import type { AgentIdea, AgentMember, AgentRequestSummary, AgentSpace, AgentTaskSummary } from "../../shared/schemas/agent-tools.schema.js";
+import type { ResolvedAgentToken } from "./agent-tokens.js";
+/**
+ * Logique de l'API agent : agent appelant (jeton résolu), demande pour
+ * laquelle il agit, résolution des tâches et des membres dans l'espace du
+ * jeton, contexte textuel et structuré d'une demande, et résumés français
+ * des actions, affichés dans la GUI.
+ */
+/** Agent qui appelle l'API : son jeton, le propriétaire du jeton et l'espace couvert. */
+export type AgentCaller = ResolvedAgentToken;
+export declare function agentActor(agent: AgentCaller, requestId: string): Actor;
+/**
+ * Exécute `fn` dans une mutation de l'agent pour la demande `requestId`. La
+ * demande et tout ce que `fn` lit sont vérifiés et lus dans la transaction
+ * de l'écriture.
+ */
+export declare function actFor<T>(store: Store, agent: AgentCaller, requestId: string, fn: (tx: Mutation, space: Space) => T): T;
+/** Demande de l'espace du jeton ; une demande d'un autre espace est introuvable pour l'agent. */
+export declare function requestOfSpace(store: Store, agent: AgentCaller, requestId: string): AgentRequest;
+/**
+ * Demande pour laquelle l'agent veut écrire : elle vise l'espace du jeton,
+ * elle est `processing`, prise par ce jeton, et le propriétaire du jeton est
+ * encore membre de l'espace. Vérifié à chaque appel.
+ */
+export declare function actingRequest(store: Store, agent: AgentCaller, requestId: string): {
+    request: AgentRequest;
+    space: Space;
+};
+export declare function userLabel(user: User): string;
+export declare function taskKey(store: Store, task: Task): string;
+/** Tâche de l'espace désignée par son identifiant ou sa clé (`ORG-41`). */
+export declare function resolveTask(store: Store, space: Space, ref: string): Task;
+/** Idée de l'espace. */
+export declare function resolveIdea(store: Store, space: Space, ideaId: string): Idea;
+/** Membres de l'espace désignés par leur identifiant ou leur adresse e-mail. */
+export declare function resolveMembers(store: Store, space: Space, refs: readonly string[]): User[];
+/** Arborescence de l'espace : chaque tâche puis ses sous-tâches, par colonne et rang. */
+export declare function spaceTree(store: Store, space: Space): string[];
+/** Membres de l'espace : nom, adresse, rôle et identifiant (pour set_assignees). */
+export declare function memberLines(store: Store, space: Space): string[];
+/** Durée écoulée depuis `iso`, en anglais. */
+export declare function ago(iso: string, now?: Date): string;
+/** Résumé d'une demande pour list_requests. */
+export declare function requestLine(store: Store, agent: AgentCaller, request: AgentRequest): string;
+/** Contexte complet d'une demande, renvoyé par claim_request. */
+export declare function requestContext(store: Store, agent: AgentCaller, request: AgentRequest): string;
+/** Idées actives récentes de la boîte à idées d'un espace. */
+export declare function recentIdeas(store: Store, space: Space): Idea[];
+/** Arbre des tâches, membres et idées récentes d'un espace, pour claim_request et get_context. */
+export declare function spaceContextLines(store: Store, space: Space): string[];
+export declare function spaceData(space: Space): AgentSpace;
+export declare function memberData(store: Store, space: Space): AgentMember[];
+export declare function taskData(store: Store, task: Task): AgentTaskSummary;
+/** Tâches d'un espace dans l'ordre de l'arbre : chaque tâche puis ses sous-tâches, par colonne et rang. */
+export declare function treeData(store: Store, space: Space): AgentTaskSummary[];
+export declare function ideaData(store: Store, idea: Idea): AgentIdea;
+export declare function requestData(store: Store, agent: AgentCaller, request: AgentRequest): AgentRequestSummary;
+export declare function quote(text: string, max?: number): string;
+/** Résumé d'une création de tâche. */
+export declare function createdTaskSummary(store: Store, task: Task): string;
+/** Résumé des champs changés d'une tâche, et nature de l'opération. */
+export declare function taskUpdateSummary(store: Store, before: TaskSnapshot, after: TaskSnapshot): {
+    summary: string;
+    operation: "update" | "move";
+};
+/** Résumé d'un changement d'assignés. */
+export declare function assigneesSummary(store: Store, before: readonly string[], after: readonly string[], test: boolean): string;
+/** Vérifie qu'un texte libre n'est pas vide ; le message dit quoi fournir. */
+export declare function requireText(value: string, what: string): string;