@astrale-domains/shell 0.1.0-beta.48 → 0.1.0-beta.50

package/README.md

@@ -1,8 +1,8 @@
 # Shell Domain
 
 Shell owns two concrete Identity classes, User and Group, the member_of_group relation,
-the admin/member/applications Core groups, the Namespace class and its alias relation, the `views`
-Core Namespace, three static methods, three Namespace methods, one Domain function, and one
+the admin/member/applications/view-only Core groups, the Namespace class and its alias relation, the
+view_access relation, the `views` Core Namespace, three static methods, one User method, three Namespace methods, two Domain functions, and one
 application View, which is its entrypoint. The Schema names the Domain `Shell`. There is no Space, setup function, personal home, or public repair method.
 
 ## Contracts
@@ -13,6 +13,17 @@ application View, which is its entrypoint. The Schema names the Domain `Shell`.
 | Group.assignMember | `{ member: UserPath \| GroupPath, group: GroupPath }` | `{}` |
 | Group.unassignMember | Same | `{}` |
 
+| User method | Input | Output |
+| --- | --- | --- |
+| User.recordProfile | `{ email?: string, displayName?: string }` | `{}` |
+
+An account records the email and display name it signs in with, so the directory can name it, in
+`claimedEmail` and `claimedName`: named apart from the `email` or `displayName` a Domain extending
+User declares for its own profile. Its
+`isSelf` Policy admits the account itself alone, and Shell writes, with its own authority, only what
+changed; an email is kept in lower case. The values come from the account, not from its identity
+provider: they name it for display and decide nothing. The GUI records them at each sign-in.
+
 | Namespace method | Input | Output |
 | --- | --- | --- |
 | Namespace.link | `{ name: string, target: NodePath }` | `{}` |
@@ -22,6 +33,7 @@ application View, which is its entrypoint. The Schema names the Domain `Shell`.
 | Domain function | Input | Output |
 | --- | --- | --- |
 | listEntrypoints | `{}` | `{ entrypoints: { origin, name, view }[] }` |
+| assignViews | `{ assignments: { identity, set?, unset? }[] }` | `{}` |
 
 listEntrypoints reads, with Shell's own authority, every Kernel `of_domain` locator whose View has
 an outgoing `entrypoint` Edge, and returns one entry per Domain in origin order: its origin, the
@@ -103,6 +115,37 @@ Every other failure propagates. Core admin holds the three methods, `read` and `
 Namespace, and every operation on alias. Administration follows `administersShellClass` on the
 Namespace, as for Groups.
 
+## View access
+
+**A View given to an account decides where it lands, never what it reads.** `view_access` runs from
+a User or a Group to one Kernel View. The Core group `view-only` limits its members to the Views
+they hold, directly or through a group they are a direct member of; membership in `view-only` and
+in Core `admin` counts the same way. Everyone else, and every administrator, opens the workspace as
+before. Nothing else changes: the View's own Domain still
+guards every Node it shows, and `View.resolve` and `listEntrypoints` answer as before.
+
+| Fact | Who writes it | How |
+| --- | --- | --- |
+| `view_access(holder → View)` | Core admin | `assignViews`, or a Mutation that creates or deletes the Edge. It carries no property. |
+| `member_of_group(user → view-only)` | Core admin | `Group.assignMember` / `Group.unassignMember`. |
+
+`view_access` declares `read: true` and `traverse: true`, as `alias` does. Its target is a
+Class Shell does not own, so it detaches when its View is deleted, by a Mutation or by a release
+that removes the View. Clients read a visitor's access with its own Queries
+(`shell.views.access()`): never a read function. A Shell release without `view-only` limits no one.
+
+`assignViews` takes, for each identity (a User or a Group, by `@NodeId`), the Views to give
+(`set`) and to withdraw (`unset`), by `@NodeId`. It reads the identities' `view_access` Edges and
+writes only what differs, in one Mutation guarded by that read, with Shell's own authority: a View
+already given or already withdrawn costs nothing, and a concurrent change refuses the whole write
+(`VIEW_ACCESS_CONFLICT`). An identity listed twice gets both lists; one View both given and
+withdrawn is refused. One call changes at most 40 identities and 20 Views per list. Core admin
+holds it, and may share `can_use` on it. It never changes `view-only`: whether an identity opens the workspace stays its
+membership, which `Group.assignMember` changes.
+
+To limit an invited person to one View: invite them, assign them to `view-only`, give them the
+View with `assignViews`, and give the View an alias in `views` so `/v/<name>` opens it.
+
 ## Flows
 
 ```text
@@ -142,18 +185,22 @@ Kernel E2E evidence, not a handler test, qualifies this behavior.
 
 The Shell principal requests all Kernel root functions, the required extends_with operations,
 and the declared grant/revoke authority. Core admin receives the full declared Shell profile,
-including invite, assignMember, unassignMember, link, unlink and rename so humans inheriting admin
-can call those methods. Core member receives Download, Introspect, Query, Mutate, View.resolve and
-listEntrypoints, not blanket class-read grants. Core applications receives listEntrypoints,
+including invite, recordProfile, assignMember, unassignMember, link, unlink, rename and assignViews
+so humans inheriting admin can call those methods. Core member receives Download, Introspect, Query,
+Mutate, View.resolve, listEntrypoints and recordProfile, not blanket class-read grants. Core applications receives listEntrypoints,
 View.resolve and Query.
 The Domain definition's requirements, including Core Identity capabilities in requirements.core, are owned by domain.ts and materialized by installation,
 never by invitation handlers.
 
 The sole application entrypoint uses the Vite React frontend at /, composed with
-`@astrale-os/shell-react` and `@astrale-os/ui`. It lists visible User/Group families in two tabs
-under the caller's session, with loading/empty/error states and independent refresh.
-Users display their concrete class and Node ID, not a guessed foreign profile.
-It does not proxy privileged directory reads or enumerate installed applications.
+`@astrale-os/shell-react` and `@astrale-os/ui`. It administers the instance under the caller's own
+session, in two tabs. **Access** lists users, then groups: whether each opens the whole OS or only its Views (two spelled-out options
+over its `view-only` membership; an administrator always does, a Core group is decided by its role)
+and, through a picker, the installed Views given to it. **Groups** lists the groups and the direct
+members of the chosen one, to add or remove. Every change applies at once and comes back with a
+message when the Kernel refuses it. A user shows its recorded display name and email, or its concrete
+class when it recorded none, never a guessed foreign profile. Every read is a Query under the
+caller's rights; the screen proxies no privileged read.
 
 ## Source and qualification
 

package/dist/domain.d.ts

@@ -14,6 +14,8 @@ declare const frontend: import("@astrale-os/sdk/view").Frontend<import("@astrale
             readonly extends: readonly [import("@astrale-os/sdk/schema").KernelClass<"Identity">];
             readonly properties: {
                 readonly creationKey: import("zod").ZodOptional<import("zod").ZodString>;
+                readonly claimedEmail: import("zod").ZodOptional<import("zod").ZodString>;
+                readonly claimedName: import("zod").ZodOptional<import("zod").ZodString>;
             };
             readonly methods: {
                 readonly invite: import("@astrale-os/sdk/schema").Method<import("@astrale-os/sdk/schema").CallableProjection<{
@@ -27,6 +29,13 @@ declare const frontend: import("@astrale-os/sdk/view").Frontend<import("@astrale
                         state: "accepted" | "cancelled" | "completed" | "expired" | "failed" | "pending" | "registered" | "registering";
                     };
                 }, "authorized", true, false, undefined, undefined>>;
+                readonly recordProfile: import("@astrale-os/sdk/schema").Method<import("@astrale-os/sdk/schema").CallableProjection<{
+                    email?: string | undefined;
+                    displayName?: string | undefined;
+                }, {
+                    readonly mode: 'value';
+                    readonly value: Record<string, never>;
+                }, "authorized", false, false, undefined, undefined>>;
             };
         }>;
         readonly Group: import("@astrale-os/sdk/schema").AuthoredNodeClass<{
@@ -115,6 +124,22 @@ declare const frontend: import("@astrale-os/sdk/view").Frontend<import("@astrale
             readonly constraints: Record<never, never>;
             readonly effectiveProperties: never;
         }>;
+        readonly view_access: import("@astrale-os/sdk/schema").DirectedEdgeClass<{
+            readonly depth: 0;
+            readonly abstract: false;
+            readonly extends: readonly [];
+            readonly properties: never;
+            readonly source: {
+                readonly as: "holder";
+                readonly outgoing: "0..*";
+            };
+            readonly target: {
+                readonly as: "view";
+                readonly incoming: "0..*";
+            };
+            readonly constraints: Record<never, never>;
+            readonly effectiveProperties: never;
+        }>;
     };
     readonly functions: {
         readonly listEntrypoints: import("@astrale-os/sdk/schema").Function<import("@astrale-os/sdk/schema").CallableProjection<Record<string, never>, {
@@ -127,12 +152,23 @@ declare const frontend: import("@astrale-os/sdk/view").Frontend<import("@astrale
                 }[];
             };
         }, "authorized", false, false, undefined, undefined>>;
+        readonly assignViews: import("@astrale-os/sdk/schema").Function<import("@astrale-os/sdk/schema").CallableProjection<{
+            assignments: {
+                identity: string;
+                set?: string[] | undefined;
+                unset?: string[] | undefined;
+            }[];
+        }, {
+            readonly mode: 'value';
+            readonly value: Record<string, never>;
+        }, "authorized", false, false, undefined, undefined>>;
     };
     readonly policies: {
         readonly belongsToGroup: import("@astrale-os/sdk/schema").Policy;
         readonly ownsClass: import("@astrale-os/sdk/schema").Policy;
         readonly administersShellClass: import("@astrale-os/sdk/schema").Policy;
         readonly usesFunction: import("@astrale-os/sdk/schema").Policy;
+        readonly isSelf: import("@astrale-os/sdk/schema").Policy;
     };
     readonly views: {
         readonly application: import("@astrale-os/sdk/schema").View;
@@ -143,6 +179,7 @@ declare const frontend: import("@astrale-os/sdk/view").Frontend<import("@astrale
             readonly applications: import("@astrale-os/sdk/schema").CoreNode;
             readonly member: import("@astrale-os/sdk/schema").CoreNode;
             readonly views: import("@astrale-os/sdk/schema").CoreNode;
+            readonly 'view-only': import("@astrale-os/sdk/schema").CoreNode;
         };
     };
 }, {

package/dist/domain.js

@@ -29,6 +29,7 @@ const domainRequirements = requirements({
             functions: [
                 ...KernelRootFunctions,
                 S.classes.User.static.methods.invite,
+                S.classes.User.methods.recordProfile,
                 S.classes.Group.static.methods.assignMember,
                 S.classes.Group.static.methods.unassignMember,
                 S.classes.Namespace.methods.link,
@@ -36,6 +37,7 @@ const domainRequirements = requirements({
                 S.classes.Namespace.methods.rename,
                 // Core Edges cannot author Kernel extends_with, so administrators hold it directly.
                 S.functions.listEntrypoints,
+                S.functions.assignViews,
             ],
             classes: [
                 { class: S.classes.User, operations: ['create', 'read', 'traverse', 'update', 'delete'] },
@@ -49,6 +51,8 @@ const domainRequirements = requirements({
                 },
                 { class: S.classes.Namespace, operations: ['read', 'traverse'] },
                 { class: S.classes.alias, operations: ['create', 'read', 'traverse', 'update', 'delete'] },
+                // assignViews gives and withdraws Views; a Mutation may too. view_access carries no property.
+                { class: S.classes.view_access, operations: ['create', 'read', 'traverse', 'delete'] },
                 { class: K.classes.extends_with, operations: ['create', 'read', 'traverse', 'delete'] },
             ],
             authority: {
@@ -67,6 +71,8 @@ const domainRequirements = requirements({
                 K.classes.View.static.methods.resolve,
                 // The workspace opens only on this catalogue: an invited member must be able to read it.
                 S.functions.listEntrypoints,
+                // The GUI records the email and name each account signs in with; isSelf bounds it.
+                S.classes.User.methods.recordProfile,
             ],
         },
         {

package/dist/functions/user/index.js

@@ -1 +1,2 @@
 export { invite } from './invite-user.js';
+export { recordProfile } from './record-profile.js';

package/dist/functions/user/record-profile.js

@@ -0,0 +1,18 @@
+import { defineAction } from '@astrale-os/sdk/action';
+import { recordUserProfile } from '../../mutations/user/index.js';
+import { readUserProfile } from '../../queries/user/index.js';
+/**
+ * One read and, only when something changed, one write, with Shell's own authority: the policy
+ * admits the account itself alone. An email is kept in lower case.
+ */
+export const recordProfile = defineAction()('User.recordProfile', async ({ input, self, query, mutate }) => {
+    const asked = {
+        ...(input.email === undefined ? {} : { email: input.email.trim().toLowerCase() }),
+        ...(input.displayName === undefined ? {} : { displayName: input.displayName }),
+    };
+    const current = await query(readUserProfile, { user: self });
+    const set = Object.fromEntries(Object.entries(asked).filter(([key, value]) => current[key] !== value));
+    if (Object.keys(set).length > 0)
+        await mutate(recordUserProfile, { user: self, set });
+    return {};
+});

package/dist/functions/view-access/assign-views.js

@@ -0,0 +1,86 @@
+import { defineAction } from '@astrale-os/sdk/action';
+import { Path } from '@astrale-os/sdk/graph/path';
+import { setViewAccess } from '../../mutations/view-access/index.js';
+import { readViewAccess } from '../../queries/view-access/index.js';
+import { canonicalNodeId } from '../../utils/canonical-node-path/index.js';
+import { viewAccessErrors } from './view-access-errors.js';
+/**
+ * One read and at most one Mutation, both with Shell's own authority: holding `can_use` on this
+ * Function is what admits the caller, Core admin by default. The write changes only what differs
+ * from the Edges read, under their guard, so a View already given or already withdrawn costs
+ * nothing and a concurrent change refuses the whole write. An identity listed twice gets both
+ * lists; one listed with no View is not read.
+ */
+export const assignViews = defineAction()('assignViews', { errors: viewAccessErrors }, async ({ error, input, query, mutate }) => {
+    const nodeId = (reference) => {
+        const invalid = () => error('INVALID_VIEW_ASSIGNMENT_REFERENCE', {});
+        try {
+            return canonicalNodeId(reference, invalid);
+        }
+        catch {
+            throw invalid();
+        }
+    };
+    const wanted = new Map();
+    for (const assignment of input.assignments) {
+        const identity = nodeId(assignment.identity);
+        const lists = [
+            [assignment.set ?? [], true],
+            [assignment.unset ?? [], false],
+        ];
+        for (const [list, given] of lists) {
+            for (const reference of list) {
+                const view = nodeId(reference);
+                const views = wanted.get(identity) ?? new Map();
+                wanted.set(identity, views);
+                if (views.get(view) === !given) {
+                    throw error('CONTRADICTORY_VIEW_ASSIGNMENT', {
+                        identity: Path.id(identity).raw,
+                        view: Path.id(view).raw,
+                    });
+                }
+                views.set(view, given);
+            }
+        }
+    }
+    const [first, ...others] = wanted.keys();
+    if (first === undefined)
+        return {};
+    const read = () => query(readViewAccess, { identities: [first, ...others] });
+    const current = await read();
+    const { give, withdraw } = changes(wanted, current);
+    if (give.length === 0 && withdraw.length === 0)
+        return {};
+    const result = await mutate(setViewAccess, { give, withdraw, guard: current.guard });
+    if (result.ok)
+        return {};
+    switch (result.refusal) {
+        case 'ENDPOINT_NOT_FOUND':
+            // Every endpoint of a withdrawal was read: one that vanished was deleted meanwhile.
+            if (give.length > 0)
+                throw error('VIEW_ASSIGNMENT_ENDPOINT_NOT_FOUND', {});
+            throw error('VIEW_ACCESS_CONFLICT', {});
+        case 'CHANGED':
+            throw error('VIEW_ACCESS_CONFLICT', {});
+        case 'UNKNOWN': {
+            const after = changes(wanted, await read());
+            if (after.give.length === 0 && after.withdraw.length === 0)
+                return {};
+            throw error('VIEW_ACCESS_UNCONFIRMED', {});
+        }
+    }
+});
+/** What differs between the Views wanted and the Views held. */
+function changes(wanted, current) {
+    const give = [];
+    const withdraw = [];
+    for (const [identity, views] of wanted) {
+        const held = current.given.get(identity);
+        for (const [view, given] of views) {
+            if (given === (held?.has(view) ?? false))
+                continue;
+            (given ? give : withdraw).push({ identity, view });
+        }
+    }
+    return { give, withdraw };
+}

package/dist/functions/view-access/index.js

@@ -0,0 +1 @@
+export { assignViews } from './assign-views.js';

package/dist/functions/view-access/view-access-errors.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+export const viewAccessErrors = {
+    INVALID_VIEW_ASSIGNMENT_REFERENCE: {
+        family: 'VALIDATION_ERROR',
+        message: 'Identities and Views must be exact canonical @NodeId paths.',
+        details: z.strictObject({}),
+    },
+    CONTRADICTORY_VIEW_ASSIGNMENT: {
+        family: 'VALIDATION_ERROR',
+        message: 'One View is both given to and withdrawn from the same identity.',
+        details: z.strictObject({ identity: z.string(), view: z.string() }),
+    },
+    VIEW_ASSIGNMENT_ENDPOINT_NOT_FOUND: {
+        family: 'NOT_FOUND',
+        message: 'An identity is not a User or a Group, or a View to give is not a View.',
+        details: z.strictObject({}),
+    },
+    VIEW_ACCESS_CONFLICT: {
+        family: 'CONFLICT',
+        message: 'The Views of these identities changed concurrently; retry the operation.',
+        details: z.strictObject({}),
+    },
+    VIEW_ACCESS_UNCONFIRMED: {
+        family: 'CONFLICT',
+        message: 'The Views asked for could not be confirmed; retry the operation.',
+        details: z.strictObject({}),
+    },
+};

package/dist/mutations/user/index.js

@@ -0,0 +1 @@
+export { recordUserProfile } from './record-user-profile.js';

package/dist/mutations/user/record-user-profile.js

@@ -0,0 +1,13 @@
+import { defineMutation } from '@astrale-os/sdk/mutation';
+/** Set the email and display name an account recorded about itself. */
+export const recordUserProfile = defineMutation()((domain) => ({
+    id: 'shell.user.profile.record',
+    build({ user, set }, mutation) {
+        const props = {
+            ...(set.email === undefined ? {} : { claimedEmail: set.email }),
+            ...(set.displayName === undefined ? {} : { claimedName: set.displayName }),
+        };
+        mutation.updateNode({ node: { id: user }, class: domain.classes.User, props: { set: props } });
+    },
+    project: () => ({}),
+}));

package/dist/mutations/view-access/index.js

@@ -0,0 +1 @@
+export { setViewAccess } from './set-view-access.js';

package/dist/mutations/view-access/set-view-access.js

@@ -0,0 +1,29 @@
+import { defineMutation } from '@astrale-os/sdk/mutation';
+/** Give and withdraw `view_access` Edges in one guarded write. */
+export const setViewAccess = defineMutation()((domain) => ({
+    id: 'shell.view-access.set',
+    build(input, mutation) {
+        mutation.expect.query(input.guard);
+        const edge = ({ identity, view }) => ({
+            class: domain.classes.view_access,
+            source: identity,
+            target: view,
+        });
+        for (const access of input.give)
+            mutation.createEdge(edge(access));
+        for (const access of input.withdraw)
+            mutation.deleteEdge(edge(access));
+    },
+    project: () => ({ ok: true }),
+    reject: (failure) => {
+        if (failure.outcomeKnown) {
+            if (failure.code === 'MUTATION_PRECONDITION_FAILED' || failure.code === 'MUTATION_CONFLICT')
+                return { ok: false, refusal: 'CHANGED' };
+            // An endpoint reaches no Node of a Class view_access accepts.
+            if (failure.code === 'MUTATION_LOCATOR_INVALID')
+                return { ok: false, refusal: 'ENDPOINT_NOT_FOUND' };
+            throw failure;
+        }
+        return { ok: false, refusal: 'UNKNOWN' };
+    },
+}));

package/dist/queries/user/index.js

@@ -0,0 +1 @@
+export { readUserProfile } from './read-user-profile.js';

package/dist/queries/user/read-user-profile.js

@@ -0,0 +1,24 @@
+import { Path } from '@astrale-os/sdk/graph/path';
+import { defineQuery, Query, queryResult, } from '@astrale-os/sdk/query';
+/** The email and display name one account recorded; nothing for an account it cannot read. */
+export const readUserProfile = defineQuery()((domain) => {
+    const { claimedEmail: email, claimedName: displayName } = domain.classes.User.properties;
+    return {
+        id: 'shell.user.profile',
+        page: { size: 1 },
+        pagination: { maximumPages: 1 },
+        build: ({ user }) => Query.from({ nodes: [Path.id(user)] }).select({
+            kind: 'nodes',
+            projection: { kind: 'value' },
+        }),
+        project(pages) {
+            const [node] = queryResult.completeNodeValues(pages, 'Shell user profile');
+            const text = (value) => (typeof value === 'string' ? value : undefined);
+            const recorded = {
+                email: text(node?.props[email.key]),
+                displayName: text(node?.props[displayName.key]),
+            };
+            return Object.fromEntries(Object.entries(recorded).filter(([, value]) => value !== undefined));
+        },
+    };
+});

package/dist/queries/view-access/index.js

@@ -0,0 +1 @@
+export { readViewAccess } from './read-view-access.js';

package/dist/queries/view-access/read-view-access.js

@@ -0,0 +1,35 @@
+import { Path } from '@astrale-os/sdk/graph/path';
+import { Query, defineQuery, queryResult, } from '@astrale-os/sdk/query';
+/** Every `view_access` Edge from the identities, kept whole as a guard for the write it decides. */
+export const readViewAccess = defineQuery()((domain) => ({
+    id: 'shell.view-access.read',
+    build({ identities }) {
+        const held = Query.from({
+            nodes: [Path.id(identities[0]), ...identities.slice(1).map((identity) => Path.id(identity))],
+        }).expand({
+            via: [domain.classes.view_access],
+            direction: 'outgoing',
+        });
+        return held.select({
+            kind: 'edges',
+            binding: held.edge,
+            projection: { edge: 'value', source: 'reference', target: 'reference' },
+        });
+    },
+    // A guard checks at most 4,096 Edges: 16 pages of 256.
+    pagination: { maximumPages: 16 },
+    project(pages, _input, { ast, complete }) {
+        const given = new Map();
+        for (const page of pages) {
+            for (const item of queryResult.edgeItems(page, 'Shell view access')) {
+                if (item.edge.kind !== 'value')
+                    throw new TypeError('Expected an Edge value.');
+                const { source, target } = item.edge.value;
+                const views = given.get(source) ?? new Set();
+                views.add(target);
+                given.set(source, views);
+            }
+        }
+        return { given, guard: { query: ast, equals: complete } };
+    },
+}));