anbaric-cloud-hosting 1.69.0 → 1.71.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-cloud-hosting",
-  "version": "1.69.0",
+  "version": "1.71.0",
   "description": "Anbaric Cloud hosting service: Postgres-backed job persistence and queuing exposed over an HTTP API",
   "license": "MIT",
   "author": "chris@anbaric.ai",
@@ -18,18 +18,18 @@
     "@aws-sdk/client-s3": "^3.1110.0",
     "@aws-sdk/client-secrets-manager": "^3.700.0",
     "@aws-sdk/client-servicediscovery": "^3.1110.0",
-    "anbaric-data-store": "^1.69.0",
-    "anbaric-plugins": "^1.69.0",
-    "anbaric-tsapi": "^1.69.0",
-    "anbaric-web": "^1.69.0",
+    "anbaric-data-store": "^1.71.0",
+    "anbaric-plugins": "^1.71.0",
+    "anbaric-tsapi": "^1.71.0",
+    "anbaric-web": "^1.71.0",
     "esbuild": "^0.28.2",
     "pg": "^8.16.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "@types/pg": "^8.15.0",
-    "anbaric-impl-cloud": "^1.69.0",
-    "anbaric-state-machine": "^1.69.0",
+    "anbaric-impl-cloud": "^1.71.0",
+    "anbaric-state-machine": "^1.71.0",
     "tsx": "^4.20.0",
     "typescript": "^7.0.2"
   },

package/src/auth/HttpMembershipService.ts

@@ -11,23 +11,35 @@ const ROLE_CACHE_TTL_MS = 60_000;
    role change is a fair trade for not calling central on each of them. */
 class HttpMembershipService implements MembershipService {
 
-    private roles = new Map<string, { role : TenantRole | undefined, expires : number }>();
+    private roles = new Map<string, { role : TenantRole | undefined, invitationToken? : string, expires : number }>();
 
     constructor(private centralUrl : string, private secret : string, private tenantSlug : string,
                 private fetchFn : FetchFn = (url, init) => fetch(url, init),
                 private cacheTtlMs : number = ROLE_CACHE_TTL_MS) {}
 
     async roleFor(userId : string) : Promise<TenantRole | undefined> {
+        return (await this.membership(userId)).role;
+    }
+
+    async joinedVia(userId : string) : Promise<string | undefined> {
+        return (await this.membership(userId)).invitationToken;
+    }
+
+    private async membership(userId : string) : Promise<{ role : TenantRole | undefined, invitationToken? : string }> {
         const cached = this.roles.get(userId);
-        if (cached && cached.expires > Date.now()) return cached.role;
+        if (cached && cached.expires > Date.now()) return cached;
 
         const response = await this.call("GET", `/members/${encodeURIComponent(userId)}`, undefined, [404]);
-        const role = response.status === 404
-            ? undefined
-            : (await response.json() as { role? : unknown }).role;
-        const found = isTenantRole(role) ? role : undefined;
-
-        this.roles.set(userId, { role: found, expires: Date.now() + this.cacheTtlMs });
+        const answer = response.status === 404
+            ? {}
+            : await response.json() as { role? : unknown, invitationToken? : unknown };
+        const found = {
+            role: isTenantRole(answer.role) ? answer.role : undefined,
+            invitationToken: typeof answer.invitationToken === "string" ? answer.invitationToken : undefined,
+            expires: Date.now() + this.cacheTtlMs,
+        };
+
+        this.roles.set(userId, found);
         return found;
     }
 
@@ -36,6 +48,11 @@ class HttpMembershipService implements MembershipService {
         return await response.json() as PendingInvitation;
     }
 
+    async inviteLink(role : TenantRole, invitedBy : Inviter, uses : number, landingApp? : string) : Promise<PendingInvitation> {
+        const response = await this.call("POST", "/invitations", { link: true, uses, role, invitedBy, landingApp });
+        return await response.json() as PendingInvitation;
+    }
+
     async pending(asking : Inviter) : Promise<Array<PendingInvitation>> {
         const response = await this.call("GET", "/invitations", undefined, [], asking);
         return await response.json() as Array<PendingInvitation>;

package/src/auth/InMemoryMembershipService.ts

@@ -6,6 +6,7 @@ class InMemoryMembershipService implements MembershipService {
 
     private invitations = new Map<string, PendingInvitation>();
     private members = new Map<string, TenantRole>();
+    private joinedThrough = new Map<string, string>();
 
     constructor(private linkBase : string = "http://localhost/invitations") {}
 
@@ -17,6 +18,35 @@ class InMemoryMembershipService implements MembershipService {
         return this.members.get(userId);
     }
 
+    // What a person who followed a link ends up as, for tests to arrange.
+    join(userId : string, role : TenantRole, token : string) : void {
+        this.members.set(userId, role);
+        this.joinedThrough.set(userId, token);
+    }
+
+    async joinedVia(userId : string) : Promise<string | undefined> {
+        return this.joinedThrough.get(userId);
+    }
+
+    async inviteLink(role : TenantRole, invitedBy : Inviter, uses : number, landingApp? : string) : Promise<PendingInvitation> {
+        const token = randomUUID();
+        const now = new Date();
+        const invitation : PendingInvitation = {
+            token,
+            role,
+            landingApp,
+            invitedBy: invitedBy.id,
+            invitedByName: invitedBy.name,
+            link: `${this.linkBase}/${token}`,
+            createdAt: now.toISOString(),
+            expiresAt: new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+            emailed: false,
+            usesRemaining: uses,
+        };
+        this.invitations.set(token, invitation);
+        return { ...invitation };
+    }
+
     async remove(userId : string, _asking : Inviter) : Promise<boolean> {
         return this.members.delete(userId);
     }

package/src/auth/MembershipService.ts

@@ -3,7 +3,8 @@ import {TenantRole} from "./TenantRole";
 type PendingInvitation = {
 
     token : string,
-    email : string,
+    // Absent for a link: nobody is named, whoever opens it may join.
+    email? : string,
     role : TenantRole,
     landingApp? : string,
     invitedBy : string,
@@ -12,6 +13,8 @@ type PendingInvitation = {
     createdAt : string,
     expiresAt : string,
     emailed? : boolean,
+    // Present for a link invitation: how many more people may join through it.
+    usesRemaining? : number,
 
 };
 
@@ -35,6 +38,13 @@ interface MembershipService {
        the invitation is accepted, so a later change of address still works. */
     invite(email : string, role : TenantRole, invitedBy : Inviter, landingApp? : string) : Promise<PendingInvitation>;
 
+    /* An invitation with no name on it: a link that admits whoever opens it
+       and signs in, up to `uses` people. */
+    inviteLink(role : TenantRole, invitedBy : Inviter, uses : number, landingApp? : string) : Promise<PendingInvitation>;
+
+    // The invitation a member came in through, when it is known.
+    joinedVia(userId : string) : Promise<string | undefined>;
+
     pending(asking : Inviter) : Promise<Array<PendingInvitation>>;
 
     revoke(token : string, asking : Inviter) : Promise<boolean>;

package/src/data-store/EntitlementStore.ts

@@ -27,7 +27,9 @@ type EntitlementGrant = {
    have until they arrive. This is the gap between the two. */
 type EntitlementOffer = {
 
-    email : string,
+    // The address the offer is held against, or null when it is held against a link.
+    email : string | null,
+    linkToken? : string,
     appId : string | null,
     entitlementId : string,
     notes : string,
@@ -58,6 +60,14 @@ interface EntitlementStore extends Entitlements {
        because the second call has nothing left to claim. */
     claim(email : string, userId : string) : Promise<number>;
 
+    /* Held against an invitation link instead of an address: granted to each
+       person who joins through the link, and kept, since the next person
+       through it is owed the same. Returns how many grants were made for this
+       person; none the second time, as they already hold them. */
+    offerForLink(linkToken : string, offers : Array<Omit<EntitlementOffer, "email" | "linkToken">>, offeredBy : string) : Promise<void>;
+
+    claimLink(linkToken : string, userId : string) : Promise<number>;
+
 }
 
 export type { EntitlementStore, EntitlementDefinition, EntitlementGrant, EntitlementOffer }

package/src/data-store/InMemoryEntitlementStore.ts

@@ -70,6 +70,27 @@ class InMemoryEntitlementStore implements EntitlementStore {
         return owed.length;
     }
 
+    async offerForLink(linkToken : string, offers : Array<Omit<EntitlementOffer, "email" | "linkToken">>, offeredBy : string) : Promise<void> {
+        for (const offer of offers) {
+            this.offers.set(`link:${linkToken} ${this.key(offer.appId, offer.entitlementId)}`,
+                { offer: { ...offer, email: null, linkToken }, offeredBy });
+        }
+    }
+
+    async claimLink(linkToken : string, userId : string) : Promise<number> {
+        const owed = [...this.offers.values()].filter(held => held.offer.linkToken === linkToken);
+        const already = await this.listGrants(userId);
+        let made = 0;
+
+        for (const held of owed) {
+            const holds = already.some(grant => grant.entitlementId === held.offer.entitlementId && (grant.appId ?? "") === (held.offer.appId ?? ""));
+            if (holds) continue;
+            await this.grant(userId, held.offer.appId, held.offer.entitlementId, held.offer.notes, held.offeredBy);
+            made++;
+        }
+        return made;
+    }
+
     private key(appId : string | null, entitlementId : string) : string {
         return `${appId ?? ""}/${entitlementId}`;
     }

package/src/data-store/InMemorySkillStore.ts

@@ -0,0 +1,31 @@
+import {Skill, SkillDraft, SkillStore} from "./SkillStore";
+
+class InMemorySkillStore implements SkillStore {
+
+    private skills = new Map<string, Skill>();
+
+    async list() : Promise<Array<Skill>> {
+        return [...this.skills.values()]
+            .sort((left, right) => left.id.localeCompare(right.id))
+            .map(skill => ({ ...skill }));
+    }
+
+    async get(id : string) : Promise<Skill | undefined> {
+        const skill = this.skills.get(id);
+        return skill && { ...skill };
+    }
+
+    async save(draft : SkillDraft) : Promise<Skill> {
+        const now = new Date();
+        const saved : Skill = { ...draft, createdAt: this.skills.get(draft.id)?.createdAt ?? now, updatedAt: now };
+        this.skills.set(draft.id, saved);
+        return { ...saved };
+    }
+
+    async remove(id : string) : Promise<boolean> {
+        return this.skills.delete(id);
+    }
+
+}
+
+export { InMemorySkillStore };

package/src/data-store/PlatformMigrations.ts

@@ -273,6 +273,38 @@ const PLATFORM_MIGRATIONS : Array<Migration> = [
         )`,
     ),
 
+    /* Guidance the tenant's builders write for the agents that work on it:
+       usage hints say when to reach for a skill, the body says what to do.
+       A platform table rather than workflow data, since apps never see it. */
+    statements("008-skills",
+        `CREATE TABLE IF NOT EXISTS anbaric_system.skills (
+            id          TEXT PRIMARY KEY,
+            title       TEXT NOT NULL,
+            usage_hints TEXT NOT NULL,
+            body        TEXT NOT NULL,
+            created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+            updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+        )`,
+    ),
+
+    // A managed skill is the operators' to change, not the tenant's.
+    statements("009-skills-locked",
+        "ALTER TABLE anbaric_system.skills ADD COLUMN IF NOT EXISTS locked BOOLEAN NOT NULL DEFAULT false",
+    ),
+
+    /* An invitation may be a link rather than an email: anyone who opens it
+       and signs in becomes a member, as many times as it allows. The
+       entitlements chosen for it are held against the link, since there is
+       no address to hold them against, and granted to each person who joins
+       through it. */
+    statements("010-invite-links",
+        "ALTER TABLE entitlement_invites ALTER COLUMN email DROP NOT NULL",
+        "ALTER TABLE entitlement_invites ADD COLUMN IF NOT EXISTS link_token TEXT",
+        "DROP INDEX IF EXISTS entitlement_invites_key",
+        `CREATE UNIQUE INDEX IF NOT EXISTS entitlement_invites_key
+            ON entitlement_invites (COALESCE(email, ''), COALESCE(link_token, ''), COALESCE(app_id, ''), entitlement_id)`,
+    ),
+
 ];
 
 export { PLATFORM_MIGRATIONS };

package/src/data-store/PostgresEntitlementStore.ts

@@ -71,7 +71,7 @@ class PostgresEntitlementStore implements EntitlementStore {
             await this.pool.query(
                 `INSERT INTO entitlement_invites (email, app_id, entitlement_id, notes, offered_by)
                  VALUES ($1, $2, $3, $4, $5)
-                 ON CONFLICT (email, COALESCE(app_id, ''), entitlement_id)
+                 ON CONFLICT (COALESCE(email, ''), COALESCE(link_token, ''), COALESCE(app_id, ''), entitlement_id)
                      DO UPDATE SET notes = EXCLUDED.notes, offered_by = EXCLUDED.offered_by`,
                 [offer.email, offer.appId, offer.entitlementId, offer.notes, offeredBy]);
         }
@@ -87,6 +87,34 @@ class PostgresEntitlementStore implements EntitlementStore {
         }));
     }
 
+    async offerForLink(linkToken : string, offers : Array<Omit<EntitlementOffer, "email" | "linkToken">>, offeredBy : string) : Promise<void> {
+        for (const offer of offers) {
+            await this.pool.query(
+                `INSERT INTO entitlement_invites (email, link_token, app_id, entitlement_id, notes, offered_by)
+                 VALUES (NULL, $1, $2, $3, $4, $5)
+                 ON CONFLICT (COALESCE(email, ''), COALESCE(link_token, ''), COALESCE(app_id, ''), entitlement_id)
+                     DO UPDATE SET notes = EXCLUDED.notes, offered_by = EXCLUDED.offered_by`,
+                [linkToken, offer.appId, offer.entitlementId, offer.notes, offeredBy]);
+        }
+    }
+
+    /* The offers stay: the link may admit more people. The grant is made once
+       per person, so a sign-in that claims again finds nothing new. */
+    async claimLink(linkToken : string, userId : string) : Promise<number> {
+        const result = await this.pool.query(
+            `INSERT INTO entitlement_grants (id, user_id, app_id, entitlement_id, notes, granted_by)
+             SELECT gen_random_uuid()::text, $2, offered.app_id, offered.entitlement_id, offered.notes, offered.offered_by
+             FROM entitlement_invites offered
+             WHERE offered.link_token = $1
+               AND NOT EXISTS (
+                   SELECT 1 FROM entitlement_grants held
+                   WHERE held.user_id = $2 AND held.entitlement_id = offered.entitlement_id
+                     AND COALESCE(held.app_id, '') = COALESCE(offered.app_id, ''))
+             RETURNING id`,
+            [linkToken, userId]);
+        return result.rowCount ?? 0;
+    }
+
     /* Claimed in one statement so a second sign-in arriving at the same moment
        cannot grant the same thing twice: the delete is what decides who owns
        each row, and only rows it actually removed become grants. */

package/src/data-store/PostgresSkillStore.ts

@@ -0,0 +1,49 @@
+import {Pool} from "pg";
+import {Skill, SkillDraft, SkillStore} from "./SkillStore";
+
+const COLUMNS = "id, title, usage_hints, body, locked, created_at, updated_at";
+
+const rowToSkill = (row : any) : Skill => ({
+    id: row.id,
+    title: row.title,
+    usageHints: row.usage_hints,
+    body: row.body,
+    locked: row.locked,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+});
+
+class PostgresSkillStore implements SkillStore {
+
+    constructor(private pool : Pool) {}
+
+    async list() : Promise<Array<Skill>> {
+        const result = await this.pool.query(`SELECT ${COLUMNS} FROM anbaric_system.skills ORDER BY id`);
+        return result.rows.map(rowToSkill);
+    }
+
+    async get(id : string) : Promise<Skill | undefined> {
+        const result = await this.pool.query(`SELECT ${COLUMNS} FROM anbaric_system.skills WHERE id = $1`, [id]);
+        return result.rows[0] && rowToSkill(result.rows[0]);
+    }
+
+    async save(draft : SkillDraft) : Promise<Skill> {
+        const result = await this.pool.query(
+            `INSERT INTO anbaric_system.skills (id, title, usage_hints, body, locked)
+             VALUES ($1, $2, $3, $4, $5)
+             ON CONFLICT (id) DO UPDATE
+                 SET title = EXCLUDED.title, usage_hints = EXCLUDED.usage_hints, body = EXCLUDED.body,
+                     locked = EXCLUDED.locked, updated_at = now()
+             RETURNING ${COLUMNS}`,
+            [draft.id, draft.title, draft.usageHints, draft.body, draft.locked]);
+        return rowToSkill(result.rows[0]);
+    }
+
+    async remove(id : string) : Promise<boolean> {
+        const result = await this.pool.query("DELETE FROM anbaric_system.skills WHERE id = $1", [id]);
+        return (result.rowCount ?? 0) > 0;
+    }
+
+}
+
+export { PostgresSkillStore };

package/src/data-store/SkillStore.ts

@@ -0,0 +1,41 @@
+/* A skill is guidance a tenant writes for the agents that build on it: when to
+   reach for it (the usage hints, which an agent reads before deciding) and
+   what to do (the body, which it reads once it has decided). Kept by the
+   platform, managed from the console, and never handed to deployed apps. */
+type Skill = {
+    id : string,
+    title : string,
+    usageHints : string,
+    body : string,
+    /* A managed skill: written by the platform's operators rather than the
+       tenant, shown as such, and not the tenant's to change or remove. */
+    locked : boolean,
+    createdAt : Date,
+    updatedAt : Date,
+};
+
+type SkillDraft = Omit<Skill, "createdAt" | "updatedAt">;
+
+/* The id ends up as the tail of a tool name an agent sees, after a fixed
+   prefix, and tool names are capped at 64 characters: hence the shape and
+   the length. */
+const SKILL_ID_SHAPE = /^[a-z0-9][a-z0-9-]{0,49}$/;
+
+const isSkillId = (value : unknown) : value is string =>
+    typeof value === "string" && SKILL_ID_SHAPE.test(value);
+
+interface SkillStore {
+
+    list() : Promise<Array<Skill>>;
+
+    get(id : string) : Promise<Skill | undefined>;
+
+    // Creates or replaces the skill with that id.
+    save(draft : SkillDraft) : Promise<Skill>;
+
+    remove(id : string) : Promise<boolean>;
+
+}
+
+export type { Skill, SkillDraft, SkillStore };
+export { SKILL_ID_SHAPE, isSkillId };

package/src/hosting/HostingServer.ts

@@ -14,6 +14,8 @@ import {MembersHandler} from "./handlers/auth/MembersHandler";
 import {BillingHandler} from "./handlers/BillingHandler";
 import {CentralBilling} from "../billing/CentralBilling";
 import {AppSettingsStore} from "../data-store/AppSettingsStore";
+import {SkillStore} from "../data-store/SkillStore";
+import {SkillsHandler} from "./handlers/SkillsHandler";
 import {Subdomains} from "../subdomains/Subdomains";
 import {AuditsHandler} from "./handlers/AuditsHandler";
 import {AuthorizeCliHandler} from "./handlers/auth/AuthorizeCliHandler";
@@ -83,7 +85,9 @@ class HostingServer {
                 fileStorageFor? : (appId : string) => FileStorage,
                 subdomains? : Subdomains,
                 billing? : CentralBilling,
-                appSettings? : AppSettingsStore) {
+                appSettings? : AppSettingsStore,
+                skills? : SkillStore,
+                operatorKey? : string) {
         const pages = new PagesHandler();
         const ping = new PingHandler(tenant);
         const jobs = new JobsHandler(persistence);
@@ -119,6 +123,8 @@ class HostingServer {
         if (memberships) publicRouter.registerApi("invitations", new InvitationsHandler(memberships, entitlements));
         if (memberships) publicRouter.registerApi("members", new MembersHandler(memberships, entitlements));
         if (billing) publicRouter.registerApi("billing", new BillingHandler(billing));
+        // People and their agents only: a deployed app has no business reading skills.
+        if (skills) publicRouter.registerApi("skills", new SkillsHandler(skills));
         const prompts = promptManagerFor && new PromptsHandler(promptManagerFor);
         if (prompts) publicRouter.registerApi("prompts", prompts);
         if (cliAuthorizer) {
@@ -170,7 +176,7 @@ class HostingServer {
             (request.method === "GET" && CLI_KEY_POLL.test(request.url.pathname));
 
         const authentication =
-            new AuthenticationMiddleware(authenticator, tokenAuthenticator, openRequests, undefined, userDirectory, memberships);
+            new AuthenticationMiddleware(authenticator, tokenAuthenticator, openRequests, undefined, userDirectory, memberships, operatorKey);
 
         /* Entitlements an inviter chose before this person had a user id were
            put aside under their email address; their first sign-in is when
@@ -178,6 +184,9 @@ class HostingServer {
         if (entitlements) {
             authentication.claimWhatIsOwed = async user => {
                 if (user.email) await entitlements.claim(user.email, user.id);
+                // Someone who came in through a link is owed what the link carries.
+                const token = await memberships?.joinedVia(user.id);
+                if (token) await entitlements.claimLink(token, user.id);
             };
         }
 

package/src/hosting/Request.ts

@@ -16,6 +16,10 @@ class Request {
     identity? : string;
     user? : User;
     tenant? : Tenant;
+    /* Set when the platform's operators are calling with the control plane's
+       key rather than anyone signing in: no user, no role, and admitted only
+       where a handler says operators belong. */
+    operator = false;
 
     readonly api : boolean;
 

package/src/hosting/handlers/SkillsHandler.ts

@@ -0,0 +1,97 @@
+import {deniesBuild} from "../../auth/TenantRole";
+import {isSkillId, Skill, SkillStore} from "../../data-store/SkillStore";
+import {Request} from "../Request";
+import {RequestHandler} from "../RequestHandler";
+
+/* The tenant's skills: guidance its builders write for the agents that work
+   on it. Anyone in the tenant may read them - an agent acting for a user
+   needs them as much as one acting for a builder - but writing them is a
+   builder's job. A managed skill is the operators' instead: written with
+   the control plane's key, marked locked, and not the tenant's to change.
+   Served to people and their agents only, never to deployed apps, which is
+   why this is registered on the public entry point alone. */
+class SkillsHandler implements RequestHandler {
+
+    constructor(private skills : SkillStore) {}
+
+    async handle(request : Request) : Promise<void> {
+        if (request.subresource) return request.notFound();
+        if (request.id) return this.handleSkill(request, request.id);
+        return this.handleCollection(request);
+    }
+
+    private async handleCollection(request : Request) : Promise<void> {
+        if (request.method !== "GET") return request.notFound();
+        return request.reply(200, (await this.skills.list()).map(skill => this.publicSkill(skill)));
+    }
+
+    private async handleSkill(request : Request, id : string) : Promise<void> {
+        switch (request.method) {
+            case "GET": {
+                const skill = await this.skills.get(id);
+                if (! skill) return request.reply(404, { error: `No skill with id "${id}"` });
+                return request.reply(200, this.publicSkill(skill));
+            }
+            case "PUT": {
+                if (! request.operator && deniesBuild(request.user?.tenantRole)) return this.refuse(request);
+                if (! isSkillId(id)) {
+                    return request.reply(400, { error: `"${id}" is not a skill id: lower-case letters, digits and hyphens, up to 50 characters` });
+                }
+                const existing = await this.skills.get(id);
+                if (existing?.locked && ! request.operator) return this.managed(request);
+
+                const body = await request.body();
+                const draft = this.draftFrom(body);
+                if (! draft) return request.reply(400, { error: "Expected a body of { title : string, usageHints : string, body : string }, none empty" });
+
+                // Only an operator makes a managed skill, and says so each time.
+                const locked = request.operator && (body as { locked? : unknown })?.locked === true;
+                return request.reply(200, this.publicSkill(await this.skills.save({ id, ...draft, locked })));
+            }
+            case "DELETE": {
+                if (! request.operator && deniesBuild(request.user?.tenantRole)) return this.refuse(request);
+                const existing = await this.skills.get(id);
+                if (! existing) return request.reply(404, { error: `No skill with id "${id}"` });
+                if (existing.locked && ! request.operator) return this.managed(request);
+
+                await this.skills.remove(id);
+                return request.reply(204);
+            }
+        }
+        request.notFound();
+    }
+
+    private refuse(request : Request) : void {
+        request.reply(403, { error: "Your role in this tenant cannot manage skills" });
+    }
+
+    private managed(request : Request) : void {
+        request.reply(403, { error: "This skill is a managed service and is not yours to change" });
+    }
+
+    private draftFrom(body : unknown) : { title : string, usageHints : string, body : string } | undefined {
+        const fields = body as Record<string, unknown> | undefined;
+        const text = (value : unknown) : string | undefined =>
+            typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+
+        const title = text(fields?.title);
+        const usageHints = text(fields?.usageHints);
+        const content = text(fields?.body);
+        return title && usageHints && content ? { title, usageHints, body: content } : undefined;
+    }
+
+    private publicSkill(skill : Skill) {
+        return {
+            id: skill.id,
+            title: skill.title,
+            usageHints: skill.usageHints,
+            body: skill.body,
+            locked: skill.locked,
+            createdAt: skill.createdAt.toISOString(),
+            updatedAt: skill.updatedAt.toISOString(),
+        };
+    }
+
+}
+
+export { SkillsHandler };

package/src/hosting/handlers/auth/InvitationsHandler.ts

@@ -5,6 +5,7 @@ import {Request} from "../../Request";
 import {RequestHandler} from "../../RequestHandler";
 
 const EMAIL_SHAPE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+const MOST_USES = 1000;
 
 /* The console's side of inviting people into this tenant: list what is
    pending, invite by email (attributed to the signed-in user), revoke.
@@ -41,11 +42,20 @@ class InvitationsHandler implements RequestHandler {
         return request.user ? { id: request.user.id, name: request.user.name } : { id: "system" };
     }
 
+    /* By email, or as a link. A link names nobody: whoever opens it and signs
+       in joins, as many times as it allows, and the entitlements chosen for
+       it are held against the link rather than an address. */
     private async invite(request : Request) : Promise<void> {
         const body = await request.body() as
-            { email? : string, role? : string, landingApp? : string, entitlements? : Array<unknown> } | undefined;
+            { email? : string, link? : unknown, uses? : unknown, role? : string, landingApp? : string, entitlements? : Array<unknown> } | undefined;
+        const asLink = body?.link === true;
         const email = String(body?.email ?? "").trim();
-        if (! EMAIL_SHAPE.test(email)) return request.reply(400, { error: "A valid email address is required" });
+        if (! asLink && ! EMAIL_SHAPE.test(email)) return request.reply(400, { error: "A valid email address is required" });
+
+        const uses = asLink ? Number(body?.uses ?? 1) : 0;
+        if (asLink && (! Number.isInteger(uses) || uses < 1 || uses > MOST_USES)) {
+            return request.reply(400, { error: `A link may be used between 1 and ${MOST_USES} times` });
+        }
 
         const role = body?.role ?? "USER";
         if (! isTenantRole(role) || role === "OWNER") {
@@ -56,13 +66,19 @@ class InvitationsHandler implements RequestHandler {
             ? body.landingApp.trim()
             : undefined;
 
-        const invitation = await this.memberships.invite(email, role, this.asking(request), landingApp);
+        const invitation = asLink
+            ? await this.memberships.inviteLink(role, this.asking(request), uses, landingApp)
+            : await this.memberships.invite(email, role, this.asking(request), landingApp);
 
         /* Put aside after the invitation exists, so nothing is held for an
-           email that was never actually invited. */
-        const chosen = this.chosenEntitlements(email, body?.entitlements);
+           email, or a link, that was never actually made. */
+        const chosen = this.chosenEntitlements(body?.entitlements);
         if (chosen.length > 0 && this.entitlements) {
-            await this.entitlements.offer(chosen, request.user?.id ?? "system");
+            if (asLink) {
+                await this.entitlements.offerForLink(invitation.token, chosen, request.user?.id ?? "system");
+            } else {
+                await this.entitlements.offer(chosen.map(offer => ({ ...offer, email })), request.user?.id ?? "system");
+            }
         }
 
         request.reply(201, { ...invitation, entitlements: chosen.length });
@@ -70,7 +86,7 @@ class InvitationsHandler implements RequestHandler {
 
     // Each is an app and an entitlement, with a null app meaning every app -
     // the same scoping a grant already has.
-    private chosenEntitlements(email : string, chosen : Array<unknown> | undefined) : Array<EntitlementOffer> {
+    private chosenEntitlements(chosen : Array<unknown> | undefined) : Array<Omit<EntitlementOffer, "email" | "linkToken">> {
         if (! Array.isArray(chosen)) return [];
 
         return chosen.flatMap(each => {
@@ -78,7 +94,6 @@ class InvitationsHandler implements RequestHandler {
             if (typeof offer?.entitlementId !== "string" || ! offer.entitlementId) return [];
 
             return [{
-                email,
                 appId: typeof offer.appId === "string" && offer.appId ? offer.appId : null,
                 entitlementId: offer.entitlementId,
                 notes: "",

package/src/hosting/middleware/AuthenticationMiddleware.ts

@@ -36,11 +36,20 @@ class AuthenticationMiddleware implements Middleware {
                 private isOpen : OpenRequestPredicate = () => false,
                 private sessionSigner : SessionSigner = new SessionSigner(),
                 private userDirectory? : UserDirectory,
-                private memberships? : MembershipService) {}
+                private memberships? : MembershipService,
+                private operatorKey? : string) {}
 
     async apply(request : Request) : Promise<boolean> {
         if (this.isOpen(request)) return true;
 
+        /* The platform's operators, presenting the control plane's own key,
+           reach exactly one thing: the managed skills they look after. Nothing
+           else is open to the key, so holding it is not a way into a tenant. */
+        if (this.operatorKey && request.resource === "skills" && request.header("x-anbaric-central-key") === this.operatorKey) {
+            request.operator = true;
+            return true;
+        }
+
         if (this.tokenAuthenticator?.handles(request.raw)) {
             const user = await this.tokenAuthenticator.authenticate(request.raw, request.rawResponse);
             if (!user) return false;

package/src/main.ts

@@ -27,6 +27,7 @@ import {DocGenerator} from "./docs/DocGenerator";
 import {GatewayDocModel} from "./docs/GatewayDocModel";
 import {PostgresAppDocsStore} from "./data-store/PostgresAppDocsStore";
 import {PostgresAppSettingsStore} from "./data-store/PostgresAppSettingsStore";
+import {PostgresSkillStore} from "./data-store/PostgresSkillStore";
 import {PostgresEntitlementStore} from "./data-store/PostgresEntitlementStore";
 import {PostgresUserDirectory} from "./data-store/PostgresUserDirectory";
 import {HttpMembershipService} from "./auth/HttpMembershipService";
@@ -156,7 +157,9 @@ const server = new HostingServer(jobs, queue, registry, buildLayer,
     tokenAuthenticator, process.env.ANBARIC_TENANT, auditRecords, plugins,
     new PostgresJobRunSchedulePersistence(pool), await loadNotifier(process.env.ANBARIC_NOTIFIER_MODULE),
     new PostgresEntitlementStore(pool), new PostgresUserDirectory(pool), memberships,
-    (appId) => new PostgresPromptManager(pool, appId), fileStorageFor, subdomains, billing, appSettings);
+    (appId) => new PostgresPromptManager(pool, appId), fileStorageFor, subdomains, billing, appSettings, new PostgresSkillStore(pool),
+    // The control plane's key, which the operators hold, is what writes a managed skill.
+    process.env.ANBARIC_CLI_KEY_LOOKUP_SECRET || undefined);
 const port = await server.listen(hostingPort);
 const internal = await server.listenInternal(internalPort);