@astrale-domains/shell 0.1.6 → 0.1.8

package/dist/functions/group/deprovision-group.js

@@ -0,0 +1,27 @@
+import { defineAction } from '@astrale-os/sdk/action';
+import { readMembers } from '../authority/index.js';
+import { deleteIdentity } from '../../mutations/identity/index.js';
+import { readProfile } from '../../queries/profile/index.js';
+import { groupErrors } from './group-errors.js';
+import { findGroup } from './group.js';
+/**
+ * The directory deleted the group (`dsync.group.deleted`): its memberships leave and it is deleted
+ * (G4). A group the directory no longer has is left as it is (A3).
+ */
+export const deprovision = defineAction()('Group.deprovision', { errors: groupErrors }, async (context) => {
+    const { input, error } = context;
+    const group = await findGroup(context, input);
+    if (group === undefined)
+        return {};
+    const members = await readMembers(context, group.id);
+    const profile = await context.query(readProfile, { kind: 'Group', node: group.id });
+    const result = await context.mutate(deleteIdentity, {
+        kind: 'Group',
+        node: group.id,
+        members,
+        ...(profile === undefined ? {} : { profile }),
+    });
+    if (!result.ok)
+        throw error('GROUP_CHANGED', {});
+    return {};
+});

package/dist/functions/group/group-errors.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+const none = z.strictObject({});
+/**
+ * The refusals of the group methods. The SDK declares no FORBIDDEN business family, so a law that
+ * forbids a change for the state of the group or its caller answers CONFLICT.
+ */
+export const groupErrors = {
+    GROUP_NOT_FOUND: {
+        family: 'NOT_FOUND',
+        message: 'No group is at this path.',
+        details: none,
+    },
+    GROUP_ATTRIBUTES_TOO_MANY: {
+        family: 'VALIDATION_ERROR',
+        message: 'A group carries at most 64 attributes.',
+        details: z.strictObject({ max: z.number() }),
+    },
+    GROUP_DIRECTORY_MANAGED: {
+        family: 'CONFLICT',
+        message: "This group is managed by your organization's directory. Change it in the directory.",
+        details: none,
+    },
+    GROUP_NOT_DIRECTORY_MANAGED: {
+        family: 'CONFLICT',
+        message: 'This group is local: only group.writer changes its members.',
+        details: none,
+    },
+    GROUP_ROLE_PROTECTED: {
+        family: 'CONFLICT',
+        message: 'This group grants a role. Only an administrator may change its members.',
+        details: z.strictObject({ role: z.string() }),
+    },
+    GROUP_MEMBERSHIP_CYCLE: {
+        family: 'CONFLICT',
+        message: 'This member already holds the group: the membership would close a cycle.',
+        details: none,
+    },
+    GROUP_CHANGED: {
+        family: 'CONFLICT',
+        message: 'The group changed concurrently; retry the operation.',
+        details: none,
+    },
+};

package/dist/functions/group/group-membership-errors.js

@@ -1,5 +1,7 @@
 import { z } from 'zod';
+import { groupErrors } from './group-errors.js';
 export const groupMembershipErrors = {
+    ...groupErrors,
     GROUP_MEMBERSHIP_ENDPOINTS_UNAVAILABLE: {
         family: 'CONFLICT',
         message: 'Shell must be able to traverse both membership endpoints before confirming membership.',
@@ -7,7 +9,7 @@ export const groupMembershipErrors = {
     },
     INVALID_GROUP_MEMBERSHIP_REFERENCE: {
         family: 'VALIDATION_ERROR',
-        message: 'Member and group must be exact canonical @NodeId paths.',
+        message: 'Members and group must be exact canonical @NodeId paths of accounts or groups.',
         details: z.strictObject({}),
     },
     GROUP_MEMBERSHIP_CONFLICT: {

package/dist/functions/group/group.js

@@ -0,0 +1,51 @@
+import { GROUP_PROFILE_PROPERTIES, groupProfileValues, } from '../../mutations/identity/index.js';
+import { readIdentities } from '../../queries/identity/index.js';
+import { readProfile } from '../../queries/profile/index.js';
+import { toAttributes } from '../../utils/index.js';
+const text = (value) => (typeof value === 'string' ? value : undefined);
+/** One group Node as Shell's laws read it, by the Property keys of the resolved Domain. */
+export function toGroup(domain, node) {
+    const properties = domain.classes.Group.properties;
+    const value = (name) => node.props[properties[name].key];
+    const read = (name) => text(value(name));
+    const values = {
+        name: read('name'),
+        description: read('description'),
+        icon: read('icon'),
+        directory: read('directory'),
+        externalId: read('externalId'),
+        attributes: toAttributes(value('attributes')),
+    };
+    return {
+        id: node.id,
+        class: node.class,
+        ...Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined)),
+    };
+}
+export async function readGroup({ query, domain }, group) {
+    const [node] = await query(readIdentities, { kind: 'Group', ids: [group] });
+    return node === undefined ? undefined : toGroup(domain, node);
+}
+export async function findGroup({ query, domain }, where) {
+    const [node] = await query(readIdentities, { kind: 'Group', where });
+    return node === undefined ? undefined : toGroup(domain, node);
+}
+/** A group is provided while it carries its directory (G2). */
+export const isProvidedGroup = (group) => group.directory !== undefined;
+/**
+ * The profile a group change writes: its profile Node when the change touches a shared value, or,
+ * for a group stored before profiles, the whole profile to create; undefined when nothing shared
+ * changes.
+ */
+export async function groupProfileTarget({ query }, group, set, unset) {
+    const shares = GROUP_PROFILE_PROPERTIES.some((key) => key in set || unset.includes(key));
+    if (!shares)
+        return undefined;
+    const profile = await query(readProfile, { kind: 'Group', node: group.id });
+    if (profile !== undefined)
+        return { id: profile };
+    const merged = { ...group, ...set };
+    for (const key of unset)
+        delete merged[key];
+    return { create: groupProfileValues(merged) };
+}

package/dist/functions/group/index.js

@@ -1,2 +1,8 @@
-export { assignMember } from './assign-member-to-group.js';
-export { unassignMember } from './unassign-member-from-group.js';
+export { create } from './create-group.js';
+export { update } from './update-group.js';
+export { remove } from './delete-group.js';
+export { assignMember, assignMembers } from './assign-member.js';
+export { unassignMember, unassignMembers } from './unassign-member.js';
+export { provision } from './provision-group.js';
+export { deprovision } from './deprovision-group.js';
+export { toGroup } from './group.js';

package/dist/functions/group/legacy/index.js

@@ -0,0 +1 @@
+export { legacyChangeForeignMembership, legacyMembersEdges } from './membership.js';

package/dist/functions/group/legacy/membership.js

@@ -0,0 +1,64 @@
+import { setGroupMembership } from '../../../mutations/group/index.js';
+import { readGroupMembership, readGroupMembershipEndpoints, } from '../../../queries/group/index.js';
+import { legacyReadCoreGroups, legacyReadMemberOfGroup, legacyReadMembersOfGroup, } from '../../../queries/group/legacy/index.js';
+/**
+ * @deprecated The legacy `member_of_group` Edges a change of a Shell group's members also converges
+ * (L-SHELL-8), read in one go for all the members: joining one of the legacy Core groups writes it
+ * beside `extends_with`, for the readers that still check it; leaving any group removes it.
+ * Replaced by `extends_with` alone. Removal: Shell major (delivery step 5) after 1Pact step 4.
+ */
+export async function legacyMembersEdges(context, selection, present) {
+    const [observed, legacyGroups] = await Promise.all([
+        context.query(legacyReadMembersOfGroup, selection),
+        present ? context.query(legacyReadCoreGroups, {}) : undefined,
+    ]);
+    const core = legacyGroups !== undefined && Object.values(legacyGroups).includes(selection.group);
+    return {
+        present: observed.present,
+        guard: observed.guard,
+        /** Whether a member is to keep `member_of_group`: never when it leaves the group. */
+        wanted: (member) => present && (core || observed.present.has(member)),
+    };
+}
+/**
+ * @deprecated A Domain that extends Group changes the members of its own groups (L-SHELL-9): Shell
+ * writes both legacy Edges as before, but under that Domain's authority, since the release no
+ * longer grants Shell any grant authority over foreign Identities (AM5). Shell's group laws
+ * (G2, G3) do not apply to another Domain's Identity. Replaced by the Domain's own Identity and
+ * Roles (P5, P6). Removal: Shell major (delivery step 5) after 1Pact step 4.
+ */
+export async function legacyChangeForeignMembership(context, membership, present) {
+    const caller = context.graph.caller;
+    if (caller === undefined)
+        throw context.error('GROUP_MEMBERSHIP_ENDPOINTS_UNAVAILABLE', {});
+    const observe = async () => {
+        const endpoints = await caller.query(readGroupMembershipEndpoints, membership);
+        if (!endpoints.visible)
+            throw context.error('GROUP_MEMBERSHIP_ENDPOINTS_UNAVAILABLE', {});
+        const [authority, legacy] = await Promise.all([
+            caller.query(readGroupMembership, membership),
+            caller.query(legacyReadMemberOfGroup, membership),
+        ]);
+        const edges = [
+            { edge: 'authority', current: authority.present, present, guard: authority.guard },
+            { edge: 'legacy', current: legacy.present, present, guard: legacy.guard },
+        ];
+        return { endpoints: endpoints.guard, edges };
+    };
+    const matches = (edges) => edges.every(({ current, present: wanted }) => current === wanted);
+    const current = await observe();
+    if (matches(current.edges))
+        return {};
+    const result = await caller.mutate(setGroupMembership, { ...membership, ...current });
+    if (result.ok)
+        return {};
+    if (result.outcomeKnown) {
+        if (result.rule === 'cycle')
+            throw context.error('GROUP_MEMBERSHIP_CYCLE', {});
+        throw context.error('GROUP_MEMBERSHIP_CONFLICT', { cause: result.code });
+    }
+    const recovered = await observe();
+    if (matches(recovered.edges))
+        return {};
+    throw context.error('GROUP_MEMBERSHIP_UNCONFIRMED', { cause: result.code, outcomeKnown: false });
+}

package/dist/functions/group/membership-laws.js

@@ -0,0 +1,37 @@
+import { authority } from '../authority/index.js';
+import { isProvidedGroup } from './group.js';
+/**
+ * G2 and G3 for one change of a Shell group's members. A provided group changes its members only
+ * through its directory, a local one through `group.writer`; a group that holds a Role, directly or
+ * through what it extends, only by an admin or its directory. A member that would join a group it
+ * already holds is refused by the Kernel, which keeps `extends_with` acyclic.
+ */
+export async function membershipRefusal(capabilities, group) {
+    const authorities = authority(capabilities);
+    const provided = isProvidedGroup(group);
+    if (provided) {
+        if (!(await authorities.callerHolds('directory.provisioner'))) {
+            return { code: 'GROUP_DIRECTORY_MANAGED' };
+        }
+    }
+    else if (!(await authorities.callerHolds('group.writer'))) {
+        return { code: 'GROUP_NOT_DIRECTORY_MANAGED' };
+    }
+    if (!provided) {
+        const role = await roleProtected(capabilities, group);
+        if (role !== undefined)
+            return { code: 'GROUP_ROLE_PROTECTED', role };
+    }
+    return undefined;
+}
+/**
+ * G3: the Role a group holds, when the caller is no admin and so may not change who holds it,
+ * through its members or by deleting it.
+ */
+export async function roleProtected(capabilities, group) {
+    const authorities = authority(capabilities);
+    const role = await authorities.heldRole(group.id);
+    if (role === undefined || (await authorities.callerHolds('workspace.admin')))
+        return undefined;
+    return role;
+}

package/dist/functions/group/provision-group.js

@@ -0,0 +1,33 @@
+import { defineAction } from '@astrale-os/sdk/action';
+import { Path } from '@astrale-os/sdk/graph/path';
+import { createGroup, updateGroup } from '../../mutations/identity/index.js';
+import { groupErrors } from './group-errors.js';
+import { findGroup, groupProfileTarget } from './group.js';
+/**
+ * Create or rename the group a directory provides (`dsync.group.created`, `dsync.group.updated`).
+ * Replaying an event writes nothing (A3).
+ */
+export const provision = defineAction()('Group.provision', { errors: groupErrors }, async (context) => {
+    const { input, error } = context;
+    const { directory, externalId, name } = input;
+    const existing = await findGroup(context, { directory, externalId });
+    if (existing !== undefined) {
+        if (existing.name !== name) {
+            const profile = await groupProfileTarget(context, existing, { name }, []);
+            const result = await context.mutate(updateGroup, {
+                group: existing.id,
+                set: { name },
+                ...(profile === undefined ? {} : { profile }),
+            });
+            if (!result.ok)
+                throw error('GROUP_CHANGED', {});
+        }
+        return { group: Path.id(existing.id).raw, created: false };
+    }
+    const result = await context.mutate(createGroup, {
+        values: { name, directory, externalId },
+    });
+    if (!result.ok)
+        throw error('GROUP_CHANGED', {});
+    return { group: Path.id(result.group).raw, created: true };
+});

package/dist/functions/group/unassign-member.js

@@ -0,0 +1,7 @@
+import { defineAction } from '@astrale-os/sdk/action';
+import { changeGroupMembers, changeGroupMembership } from './change-group-membership.js';
+import { groupMembershipErrors } from './group-membership-errors.js';
+/** Withdraw one account or group from a group, in one read and one write. */
+export const unassignMember = defineAction()('Group.unassignMember', { errors: groupMembershipErrors }, (context) => changeGroupMembership(context, false));
+/** Withdraw several accounts or groups from a group, in one commit. */
+export const unassignMembers = defineAction()('Group.unassignMembers', { errors: groupMembershipErrors }, (context) => changeGroupMembers(context, context.input, false));

package/dist/functions/group/update-group.js

@@ -0,0 +1,55 @@
+import { defineAction } from '@astrale-os/sdk/action';
+import { updateGroup } from '../../mutations/identity/index.js';
+import { MAX_ATTRIBUTES, boundedAttributes } from '../../utils/index.js';
+import { sameJson } from '../../utils/index.js';
+import { groupErrors } from './group-errors.js';
+import { groupProfileTarget, isProvidedGroup, readGroup } from './group.js';
+/**
+ * Rename, describe, or change the icon or the attributes of a group; a provided group's name is
+ * its directory's (G2), its attributes the instance's own (AM11).
+ */
+export const update = defineAction()('Group.update', { errors: groupErrors }, async (context) => {
+    const { input, error, self } = context;
+    const group = await readGroup(context, self);
+    if (group === undefined)
+        throw error('GROUP_NOT_FOUND', {});
+    if (isProvidedGroup(group) && input.name !== undefined && input.name !== group.name) {
+        throw error('GROUP_DIRECTORY_MANAGED', {});
+    }
+    const set = {};
+    const unset = [];
+    for (const key of ['name', 'description', 'icon']) {
+        const value = input[key];
+        if (value === undefined)
+            continue;
+        if (value === null) {
+            if (group[key] !== undefined)
+                unset.push(key);
+        }
+        else if (value !== group[key])
+            set[key] = value;
+    }
+    if (input.attributes === null) {
+        if (group.attributes !== undefined)
+            unset.push('attributes');
+    }
+    else if (input.attributes !== undefined) {
+        const attributes = boundedAttributes(input.attributes);
+        if (attributes === undefined)
+            throw error('GROUP_ATTRIBUTES_TOO_MANY', { max: MAX_ATTRIBUTES });
+        if (!sameJson(attributes, group.attributes))
+            set.attributes = attributes;
+    }
+    if (Object.keys(set).length === 0 && unset.length === 0)
+        return {};
+    const profile = await groupProfileTarget(context, group, set, unset);
+    const result = await context.mutate(updateGroup, {
+        group: self,
+        set: set,
+        unset,
+        ...(profile === undefined ? {} : { profile }),
+    });
+    if (!result.ok)
+        throw error('GROUP_CHANGED', {});
+    return {};
+});

package/dist/functions/invitation/index.js

@@ -0,0 +1,2 @@
+export { send } from './send-invitation.js';
+export { accept, cancel, resend } from './invitation-methods.js';

package/dist/functions/invitation/invitation-errors.js

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export const invitationErrors = {
+    INVITATION_NOT_FOUND: {
+        family: 'NOT_FOUND',
+        message: 'No invitation the caller reads.',
+        details: z.strictObject({}),
+    },
+    INVITATION_NOT_PENDING: {
+        family: 'CONFLICT',
+        message: 'The invitation is no longer pending: invite the account again.',
+        details: z.strictObject({}),
+    },
+};

package/dist/functions/invitation/invitation-methods.js

@@ -0,0 +1,41 @@
+import { defineAction } from '@astrale-os/sdk/action';
+import { readInvitation } from '../../queries/invitation/index.js';
+import { invitationErrors } from './invitation-errors.js';
+import { invitationSignal } from './send-invitation.js';
+/** The pending invitation a method acts on, or its refusal. */
+function pending(invitation, error) {
+    if (invitation === undefined)
+        throw error('INVITATION_NOT_FOUND', {});
+    if (invitation.status !== 'pending')
+        throw error('INVITATION_NOT_PENDING', {});
+    return invitation;
+}
+/**
+ * Send the run of a pending invitation its next event. The Shell signals under its own Domain
+ * authority: the Kernel lets only the Domain that owns a run signal it.
+ */
+async function signal(kernel, invitation, value) {
+    await kernel.execution.signal(invitation.execution, {
+        name: invitationSignal(invitation.round),
+        value,
+    });
+}
+/** Send the email of a pending invitation again: same invitation, same run. */
+export const resend = defineAction()('Invitation.resend', { errors: invitationErrors }, async (context) => {
+    const invitation = pending(await context.query(readInvitation, { invitation: context.self }), context.error);
+    await signal(context.kernel, invitation, { kind: 'resend' });
+    return {};
+});
+/** Accept a pending invitation at the first sign-in: the run binds the account (U8). */
+export const accept = defineAction()('Invitation.accept', { errors: invitationErrors }, async (context) => {
+    const invitation = pending(await context.query(readInvitation, { invitation: context.self }), context.error);
+    const { iss, sub } = context.input;
+    await signal(context.kernel, invitation, { kind: 'accepted', iss, sub });
+    return {};
+});
+/** Cancel a pending invitation: its run marks it cancelled. */
+export const cancel = defineAction()('Invitation.cancel', { errors: invitationErrors }, async (context) => {
+    const invitation = pending(await context.query(readInvitation, { invitation: context.self }), context.error);
+    await context.kernel.execution.cancel(invitation.execution);
+    return {};
+});

package/dist/functions/invitation/send-invitation.js

@@ -0,0 +1,131 @@
+import { defineWorkflow } from '@astrale-os/sdk/workflow';
+import { inviteErrors, readAccount, userErrors } from '../user/index.js';
+import { InvitationRequestFailure } from '../../integrations/user-invitation/index.js';
+import { bindAccount, createInvitation, updateInvitation } from '../../mutations/invitation/index.js';
+import { readInvitation, readPendingInvitations } from '../../queries/invitation/index.js';
+import { canonicalNodeId } from '../../utils/canonical-node-path/index.js';
+const errors = { ...inviteErrors, ...userErrors };
+/** How long an invitation waits for its first sign-in. */
+export const INVITATION_TTL_MS = 7 * 24 * 3_600_000;
+/** The signal name of one round: a name is delivered once, so each event moves to the next. */
+export const invitationSignal = (round) => `event-${round}`;
+/**
+ * Invite an account and keep its invitation until it ends: record it, have Admin send the email,
+ * then wait for the first sign-in (`accept`), a resend, a cancel or the expiry. It grants nothing:
+ * the account holds what `User.create` or an admin gave it.
+ *
+ * An account has at most one pending invitation. When one is pending for the same email, this run
+ * has it resent, with a full time to live again, and ends. For another email, it cancels it and
+ * records a new one; Admin replaces its own link when it receives the new request.
+ */
+export const send = defineWorkflow()('Invitation.send', { errors }, async (context) => {
+    const { step, execution, awaitSignal, cancelled, error } = context;
+    const user = canonicalNodeId(context.input.user, () => error('INVALID_INVITATION_REFERENCE', {}));
+    const account = await step.run('read-account', ({ query }) => readAccount({ query, domain: context.domain }, user));
+    if (account === undefined)
+        throw error('USER_NOT_FOUND', {});
+    if (account.frozen)
+        throw error('USER_SUSPENDED', {});
+    if (account.email === undefined)
+        throw error('USER_EMAIL_INVALID', {});
+    const email = account.email;
+    // Stop the runs of replaced invitations: each finds its invitation closed and ends.
+    const stop = (runs) => step.run('stop-replaced', async ({ kernel }) => {
+        for (const { execution: ref } of runs) {
+            await kernel.execution.cancel(ref).catch(() => undefined);
+        }
+    });
+    const retire = async (invitations) => {
+        for (const [index, { id }] of invitations.entries()) {
+            await step.mutate(`retire-${index}`, updateInvitation, {
+                invitation: id,
+                status: 'cancelled',
+            });
+        }
+        await stop(invitations);
+    };
+    // Close the invitation, unless another run already closed it (a replacement).
+    const close = async (name, status) => {
+        const current = await step.run(`read-${name}`, ({ query }) => query(readInvitation, { invitation }));
+        if (current?.status !== 'pending')
+            return { status: 'cancelled' };
+        await step.mutate(name, updateInvitation, { invitation, status });
+        return { status };
+    };
+    const pending = await step.run('read-pending', ({ query }) => query(readPendingInvitations, { user }));
+    const same = pending.find((previous) => previous.email === email);
+    // Its run sends the email again and restarts the time to live. A run that no longer answers
+    // has its invitation replaced instead.
+    const resent = same !== undefined &&
+        (await step.run('resend-pending', ({ kernel }) => kernel.execution
+            .signal(same.execution, {
+            name: invitationSignal(same.round),
+            value: { kind: 'resend' },
+        })
+            .then(() => true, () => false)));
+    if (resent) {
+        const others = pending.filter((previous) => previous !== same);
+        if (others.length > 0)
+            await retire(others);
+        return { status: 'pending' };
+    }
+    const startedAt = await step.run('clock', () => Date.now());
+    let expiresAt = startedAt + INVITATION_TTL_MS;
+    const { invitation } = await step.mutate('record-invitation', createInvitation, {
+        user,
+        execution: execution.id,
+        expiresAt: new Date(expiresAt).toISOString(),
+        email,
+        replaces: pending.map((previous) => previous.id),
+    });
+    if (pending.length > 0)
+        await stop(pending);
+    const requestedBy = execution.initiator.caller ?? execution.initiator.principal;
+    const sendEmail = async (round) => {
+        try {
+            await step.run(`send-email-${round}`, ({ integrations: providers }) => providers.enrollment.invite({
+                requestId: `${execution.id}:${round}`,
+                user,
+                email,
+                requestedBy: String(requestedBy),
+            }));
+        }
+        catch (cause) {
+            if (cause instanceof InvitationRequestFailure) {
+                throw error(cause.code, { requestId: `${execution.id}:${round}` });
+            }
+            throw cause;
+        }
+    };
+    try {
+        await sendEmail(0);
+        for (let round = 0;; round += 1) {
+            const now = await step.run(`clock-${round}`, () => Date.now());
+            const event = await awaitSignal(invitationSignal(round), {
+                timeoutMs: Math.max(expiresAt - now, 1),
+            });
+            if (event.kind === 'timeout')
+                return await close('expire', 'expired');
+            if (event.value.kind === 'accepted') {
+                const { iss, sub } = event.value;
+                await step.mutate('bind-account', bindAccount, { user, iss, sub });
+                await step.mutate('accept', updateInvitation, { invitation, status: 'accepted' });
+                return { status: 'accepted' };
+            }
+            // A resend is a new link from Admin, with a full time to live again.
+            await sendEmail(round + 1);
+            const resentAt = await step.run(`resent-at-${round + 1}`, () => Date.now());
+            expiresAt = resentAt + INVITATION_TTL_MS;
+            await step.mutate(`next-round-${round + 1}`, updateInvitation, {
+                invitation,
+                round: round + 1,
+                expiresAt: new Date(expiresAt).toISOString(),
+            });
+        }
+    }
+    catch (cause) {
+        if (!cancelled(cause))
+            throw cause;
+        return await close('cancel', 'cancelled');
+    }
+});

package/dist/functions/user/account.js

@@ -0,0 +1,35 @@
+import { Path } from '@astrale-os/sdk/graph/path';
+import { toAttributes } from '../../utils/index.js';
+const text = (value) => (typeof value === 'string' ? value : undefined);
+/** One account Node as Shell's laws read it, by the Property keys of the resolved Domain. */
+export function toAccount(domain, node) {
+    const properties = domain.classes.User.properties;
+    const read = (name) => node.props[properties[name].key];
+    const values = {
+        name: text(read('name')),
+        email: text(read('email')),
+        givenName: text(read('givenName')),
+        familyName: text(read('familyName')),
+        icon: text(read('icon')),
+        directory: text(read('directory')),
+        externalId: text(read('externalId')),
+        attributes: toAttributes(read('attributes')),
+        frozen: typeof read('frozen') === 'boolean' ? read('frozen') : undefined,
+    };
+    return {
+        id: node.id,
+        class: node.class,
+        ...Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined)),
+    };
+}
+/** An account is provided while it carries its directory (U3). */
+export const isProvided = (account) => account.directory !== undefined;
+/** An email in the form Shell keeps it, lower case; undefined when it is not one. */
+export function normalizeEmail(input) {
+    const email = input.trim().toLowerCase();
+    return email.length >= 3 && email.length <= 320 && /^[^\s@]+@[^\s@]+$/u.test(email)
+        ? email
+        : undefined;
+}
+/** A Node as a method returns it. */
+export const nodeReference = (id) => Path.id(id).raw;

package/dist/functions/user/create-user.js

@@ -0,0 +1,45 @@
+import { defineAction } from '@astrale-os/sdk/action';
+import { createAccount } from '../../mutations/identity/index.js';
+import { MAX_ATTRIBUTES, boundedAttributes } from '../../utils/index.js';
+import { nodeReference, normalizeEmail } from './account.js';
+// Seam L-SHELL-13: an email an account claimed before `email` existed is taken (U1).
+import { legacyClaimedAccount } from './legacy/index.js';
+import { findAccount } from './read-account.js';
+import { userErrors } from './user-errors.js';
+/**
+ * Idempotent on the email (U1): the account of the email comes back, `created: false`, whoever
+ * created it, invited or provided. A Domain needs no directory to know it (A5).
+ */
+export const create = defineAction()('User.create', { errors: userErrors }, async (context) => {
+    const { input, error } = context;
+    const email = normalizeEmail(input.email);
+    if (email === undefined)
+        throw error('USER_EMAIL_INVALID', {});
+    const attributes = input.attributes === undefined ? undefined : boundedAttributes(input.attributes);
+    if (input.attributes !== undefined && attributes === undefined) {
+        throw error('USER_ATTRIBUTES_TOO_MANY', { max: MAX_ATTRIBUTES });
+    }
+    const existing = await findAccount(context, { email });
+    if (existing !== undefined)
+        return { user: nodeReference(existing.id), created: false };
+    const claimed = await legacyClaimedAccount(context, email);
+    if (claimed !== undefined)
+        throw error('USER_EMAIL_TAKEN', { user: nodeReference(claimed) });
+    const result = await context.mutate(createAccount, {
+        values: {
+            email,
+            name: input.name,
+            ...(input.givenName === undefined ? {} : { givenName: input.givenName }),
+            ...(input.familyName === undefined ? {} : { familyName: input.familyName }),
+            ...(attributes === undefined ? {} : { attributes }),
+            frozen: false,
+        },
+    });
+    if (result.ok)
+        return { user: nodeReference(result.user), created: true };
+    // Another call created the account of this email meanwhile: it is the one.
+    const winner = await findAccount(context, { email });
+    if (winner !== undefined)
+        return { user: nodeReference(winner.id), created: false };
+    throw error('ACCOUNT_CHANGED', {});
+});

package/dist/functions/user/deactivate-user.js

@@ -0,0 +1,19 @@
+import { defineAction } from '@astrale-os/sdk/action';
+import { protectAdministrators } from './protect-administrators.js';
+import { readAccount } from './read-account.js';
+import { userErrors } from './user-errors.js';
+import { writeAccount } from './write-account.js';
+/** `frozen: true`: the Kernel refuses the account's next sign-in (U4, U5). */
+export const deactivate = defineAction()('User.deactivate', { errors: userErrors }, async (context) => {
+    const { error, self } = context;
+    const account = await readAccount(context, self);
+    if (account === undefined)
+        throw error('USER_NOT_FOUND', {});
+    const refusal = await protectAdministrators(context, self, { keepsLastAdministrator: true });
+    if (refusal !== undefined)
+        throw error(refusal, {});
+    const written = await writeAccount(context, account, { frozen: true });
+    if (written === 'CHANGED' || written === 'DUPLICATE_KEY')
+        throw error('ACCOUNT_CHANGED', {});
+    return {};
+});