anbaric-cloud-hosting 1.60.0 → 1.61.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-cloud-hosting",
-  "version": "1.60.0",
+  "version": "1.61.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.60.0",
-    "anbaric-plugins": "^1.60.0",
-    "anbaric-tsapi": "^1.60.0",
-    "anbaric-web": "^1.60.0",
+    "anbaric-data-store": "^1.61.0",
+    "anbaric-plugins": "^1.61.0",
+    "anbaric-tsapi": "^1.61.0",
+    "anbaric-web": "^1.61.0",
     "esbuild": "^0.28.2",
     "pg": "^8.16.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "@types/pg": "^8.15.0",
-    "anbaric-impl-cloud": "^1.60.0",
-    "anbaric-state-machine": "^1.60.0",
+    "anbaric-impl-cloud": "^1.61.0",
+    "anbaric-state-machine": "^1.61.0",
     "tsx": "^4.20.0",
     "typescript": "^7.0.2"
   },

package/src/app-management/BaseBuildLayer.ts

@@ -39,6 +39,8 @@ abstract class BaseBuildLayer implements BuildLayer {
     protected deployments = new Map<string, Deployment>();
     protected docGenerator? : DocGenerator;
     consumerUrlsFor : (appName : string) => Array<string> = () => [];
+
+    appRemoved : (appName : string) => void = () => {};
     private nextAppIndex = 0;
     private hydration? : Promise<void>;
 
@@ -116,6 +118,7 @@ abstract class BaseBuildLayer implements BuildLayer {
             deployment.status = "stopped";
             await this.stop(deployment);
             if (this.deployments.get(appName) === deployment) this.deployments.delete(appName);
+            this.appRemoved(appName);
         };
 
         if (deployment.status === "running" && this.consumerUrlsFor(appName).length > 0) {

package/src/app-management/BuildLayer.ts

@@ -37,6 +37,12 @@ interface BuildLayer {
     // to drain; the hosting server supplies it from its consumer registry.
     consumerUrlsFor : (appName : string) => Array<string>;
 
+    /* Called once an app is really gone, which for one that drained is some
+       minutes after the teardown returned. Whatever outlives the app - its
+       public address, in a hosted platform - is let go here, because this is
+       the only moment both paths out of teardown pass through. */
+    appRemoved : (appName : string) => void;
+
 }
 
 export type { BuildLayer, DeploymentStatus, DeploymentSummary, Draining };

package/src/app-management/appAddress.ts

@@ -0,0 +1,19 @@
+/* Where an app is served, decided in one place because the console, the CLI
+   and anything else that shows a person a link must all show the same one.
+
+   Its own address, allocated by the control plane, which is the only form on
+   Anbaric Cloud. Then the app's name under the configured host suffix, which
+   is what a self-hoster gets who has pointed their own wildcard at the
+   platform and has no control plane to allocate anything - one platform serves
+   one tenant there, so the name alone is unambiguous. Then the path form,
+   which always works and is what a platform run locally uses.
+
+   An app's own hostname serves it at the root, so links, assets and fetches
+   inside it behave as they did on the machine it was built on. */
+const appAddress = (appName : string, subdomain? : string, hostSuffix : string = process.env.ANBARIC_APP_HOST_SUFFIX ?? "") : string => {
+    if (! hostSuffix) return `/app/${appName}`;
+
+    return `https://${subdomain ?? appName}.${hostSuffix}`;
+};
+
+export { appAddress };

package/src/app-management/appHostname.ts

@@ -1,39 +1,32 @@
 /* An app is reachable at a hostname of its own, so that it is served at the
-   root of it and works exactly as it did when it was built locally. Two tenants
-   will both have a hello-world, so the tenant is part of the name.
+   root of it and works exactly as it did when it was built locally.
 
-   One label, not two: a TLS wildcard matches a single label, so app.tenant.domain
-   would need a certificate and a DNS record for every tenant, which would put a
-   person in the middle of a self-serve signup. app--tenant.domain needs neither,
-   ever. The separator is a double hyphen because an underscore is not legal in a
-   hostname and would be rejected by certificates and by some browsers. */
+   The address itself is one DNS label and belongs to the control plane, which
+   is the only thing that can see every tenant and so the only thing that can
+   keep an address unique. What is checked here is narrower and local: that the
+   app's name could be a hostname label at all, since it is the first address
+   the control plane will be asked for.
 
-const SEPARATOR = "--";
+   A hosted app whose name is already taken is given a different address rather
+   than refused, so this is about shape, never about availability. */
 
-// A DNS label may not exceed 63 characters, and the whole label is the app and
-// the tenant together, so the limit is shared between them.
-const LABEL_LIMIT = 63;
+/* A DNS label may not exceed 63 characters, and the control plane may have to
+   add a distinguishing word to a name two tenants both wanted - so a name is
+   held well short of the limit to leave room for one. */
+const NAME_LIMIT = 48;
 
 const SHAPE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 
-const hostLabelFor = (appName : string, tenant : string) : string => `${appName}${SEPARATOR}${tenant}`;
-
 /* Why this name cannot have a hostname, or undefined when it can. Returned as a
    sentence because it is shown to whoever ran the deploy. */
-const hostnameObjection = (appName : string, tenant : string) : string | undefined => {
+const hostnameObjection = (appName : string) : string | undefined => {
     if (! SHAPE.test(appName)) {
         return `"${appName}" must be lower-case letters, numbers and hyphens, starting and ending with a letter or number`;
     }
-    if (appName.includes(SEPARATOR)) {
-        return `"${appName}" cannot contain "${SEPARATOR}" - it is what separates the app from the tenant in its hostname`;
-    }
-    if (! tenant) return undefined;
-
-    const label = hostLabelFor(appName, tenant);
-    if (label.length > LABEL_LIMIT) {
-        return `"${appName}" is too long for a hostname alongside tenant "${tenant}": ${label.length} characters, and a hostname label allows ${LABEL_LIMIT}`;
+    if (appName.length > NAME_LIMIT) {
+        return `"${appName}" is too long for an app name: ${appName.length} characters, and the limit is ${NAME_LIMIT}`;
     }
     return undefined;
 };
 
-export { hostLabelFor, hostnameObjection, SEPARATOR, LABEL_LIMIT };
+export { hostnameObjection, NAME_LIMIT };

package/src/auth/HttpMembershipService.ts

@@ -31,8 +31,8 @@ class HttpMembershipService implements MembershipService {
         return found;
     }
 
-    async invite(email : string, role : TenantRole, invitedBy : Inviter) : Promise<PendingInvitation> {
-        const response = await this.call("POST", "/invitations", { email, role, invitedBy });
+    async invite(email : string, role : TenantRole, invitedBy : Inviter, landingApp? : string) : Promise<PendingInvitation> {
+        const response = await this.call("POST", "/invitations", { email, role, invitedBy, landingApp });
         return await response.json() as PendingInvitation;
     }
 

package/src/auth/InMemoryMembershipService.ts

@@ -17,13 +17,14 @@ class InMemoryMembershipService implements MembershipService {
         return this.members.get(userId);
     }
 
-    async invite(email : string, role : TenantRole, invitedBy : Inviter) : Promise<PendingInvitation> {
+    async invite(email : string, role : TenantRole, invitedBy : Inviter, landingApp? : string) : Promise<PendingInvitation> {
         const token = randomUUID();
         const now = new Date();
         const invitation : PendingInvitation = {
             token,
             email: email.trim().toLowerCase(),
             role,
+            landingApp,
             invitedBy: invitedBy.id,
             invitedByName: invitedBy.name,
             link: `${this.linkBase}/${token}`,

package/src/auth/MembershipService.ts

@@ -5,6 +5,7 @@ type PendingInvitation = {
     token : string,
     email : string,
     role : TenantRole,
+    landingApp? : string,
     invitedBy : string,
     invitedByName? : string,
     link : string,
@@ -29,7 +30,10 @@ interface MembershipService {
 
     roleFor(userId : string) : Promise<TenantRole | undefined>;
 
-    invite(email : string, role : TenantRole, invitedBy : Inviter) : Promise<PendingInvitation>;
+    /* landingApp is the app the invitation should open on rather than the
+       person's app directory. The control plane turns it into an address when
+       the invitation is accepted, so a later change of address still works. */
+    invite(email : string, role : TenantRole, invitedBy : Inviter, landingApp? : string) : Promise<PendingInvitation>;
 
     pending(asking : Inviter) : Promise<Array<PendingInvitation>>;
 

package/src/data-store/EntitlementStore.ts

@@ -22,6 +22,18 @@ type EntitlementGrant = {
 
 };
 
+/* An entitlement chosen for somebody who has not signed in yet. An invitation
+   names an email address; a grant names a user id, which that person does not
+   have until they arrive. This is the gap between the two. */
+type EntitlementOffer = {
+
+    email : string,
+    appId : string | null,
+    entitlementId : string,
+    notes : string,
+
+};
+
 /* The platform's view of entitlements: what apps can do (register, has) plus
    the management the console performs on their behalf. */
 interface EntitlementStore extends Entitlements {
@@ -36,6 +48,16 @@ interface EntitlementStore extends Entitlements {
 
     listGrants(userId? : string) : Promise<Array<EntitlementGrant>>;
 
+    // Held against an email address until whoever holds it signs in.
+    offer(offers : Array<EntitlementOffer>, offeredBy : string) : Promise<void>;
+
+    offersFor(email : string) : Promise<Array<EntitlementOffer>>;
+
+    /* Turns everything offered to this email into real grants and forgets the
+       offers. Returns how many were made, and is safe to call on every sign-in
+       because the second call has nothing left to claim. */
+    claim(email : string, userId : string) : Promise<number>;
+
 }
 
-export type { EntitlementStore, EntitlementDefinition, EntitlementGrant }
+export type { EntitlementStore, EntitlementDefinition, EntitlementGrant, EntitlementOffer }

package/src/data-store/InMemoryEntitlementStore.ts

@@ -1,10 +1,11 @@
 import {randomUUID} from "node:crypto";
-import {EntitlementDefinition, EntitlementGrant, EntitlementStore} from "./EntitlementStore";
+import {EntitlementDefinition, EntitlementGrant, EntitlementOffer, EntitlementStore} from "./EntitlementStore";
 
 class InMemoryEntitlementStore implements EntitlementStore {
 
     private definitions = new Map<string, EntitlementDefinition>();
     private grants = new Map<string, EntitlementGrant>();
+    private offers = new Map<string, { offer : EntitlementOffer, offeredBy : string }>();
 
     constructor() {
         this.definitions.set(this.key(null, "access"), { appId: null, entitlementId: "access", notes: "Global access" });
@@ -46,6 +47,29 @@ class InMemoryEntitlementStore implements EntitlementStore {
             .map(grant => ({ ...grant }));
     }
 
+    // Held against an email address; see PostgresEntitlementStore.
+    async offer(offers : Array<EntitlementOffer>, offeredBy : string) : Promise<void> {
+        for (const offer of offers) {
+            this.offers.set(`${offer.email} ${this.key(offer.appId, offer.entitlementId)}`, { offer, offeredBy });
+        }
+    }
+
+    async offersFor(email : string) : Promise<Array<EntitlementOffer>> {
+        return [...this.offers.values()]
+            .filter(held => held.offer.email === email)
+            .map(held => ({ ...held.offer }));
+    }
+
+    async claim(email : string, userId : string) : Promise<number> {
+        const owed = [...this.offers.entries()].filter(([, held]) => held.offer.email === email);
+
+        for (const [key, held] of owed) {
+            await this.grant(userId, held.offer.appId, held.offer.entitlementId, held.offer.notes, held.offeredBy);
+            this.offers.delete(key);
+        }
+        return owed.length;
+    }
+
     private key(appId : string | null, entitlementId : string) : string {
         return `${appId ?? ""}/${entitlementId}`;
     }

package/src/data-store/PlatformMigrations.ts

@@ -237,6 +237,25 @@ const PLATFORM_MIGRATIONS : Array<Migration> = [
         "CREATE INDEX jobs_heartbeat ON jobs (heartbeat_at) WHERE heartbeat_at IS NOT NULL",
     ),
 
+    /* Entitlements chosen for someone who has not arrived yet. An invitation
+       goes to an email address and a grant is made against a user id, which
+       that person does not have until the first time they sign in - so what
+       the inviter chose waits here under the email and is turned into real
+       grants at that moment. Rows are deleted as they are claimed, so this
+       table holds only what is still owed. */
+    statements("005-entitlement-invites",
+        `CREATE TABLE IF NOT EXISTS entitlement_invites (
+            email           TEXT NOT NULL,
+            app_id          TEXT,
+            entitlement_id  TEXT NOT NULL,
+            notes           TEXT NOT NULL DEFAULT '',
+            offered_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+            offered_by      TEXT NOT NULL
+        )`,
+        `CREATE UNIQUE INDEX IF NOT EXISTS entitlement_invites_key
+            ON entitlement_invites (email, COALESCE(app_id, ''), entitlement_id)`,
+    ),
+
 ];
 
 export { PLATFORM_MIGRATIONS };

package/src/data-store/PostgresEntitlementStore.ts

@@ -1,6 +1,6 @@
 import {randomUUID} from "node:crypto";
 import {Pool} from "pg";
-import {EntitlementDefinition, EntitlementGrant, EntitlementStore} from "./EntitlementStore";
+import {EntitlementDefinition, EntitlementGrant, EntitlementOffer, EntitlementStore} from "./EntitlementStore";
 
 class PostgresEntitlementStore implements EntitlementStore {
 
@@ -64,6 +64,45 @@ class PostgresEntitlementStore implements EntitlementStore {
         }));
     }
 
+    /* Held against an email address until whoever holds it signs in, because
+       an invitation names an email and a grant names a user id. */
+    async offer(offers : Array<EntitlementOffer>, offeredBy : string) : Promise<void> {
+        for (const offer of offers) {
+            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)
+                     DO UPDATE SET notes = EXCLUDED.notes, offered_by = EXCLUDED.offered_by`,
+                [offer.email, offer.appId, offer.entitlementId, offer.notes, offeredBy]);
+        }
+    }
+
+    async offersFor(email : string) : Promise<Array<EntitlementOffer>> {
+        const result = await this.pool.query(
+            `SELECT email, app_id, entitlement_id, notes FROM entitlement_invites
+             WHERE lower(email) = lower($1) ORDER BY app_id NULLS FIRST, entitlement_id`,
+            [email]);
+        return result.rows.map(row => ({
+            email: row.email, appId: row.app_id, entitlementId: row.entitlement_id, notes: row.notes,
+        }));
+    }
+
+    /* 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. */
+    async claim(email : string, userId : string) : Promise<number> {
+        const result = await this.pool.query(
+            `WITH claimed AS (
+                 DELETE FROM entitlement_invites WHERE lower(email) = lower($1)
+                 RETURNING app_id, entitlement_id, notes, offered_by
+             )
+             INSERT INTO entitlement_grants (id, user_id, app_id, entitlement_id, notes, granted_by)
+             SELECT gen_random_uuid()::text, $2, app_id, entitlement_id, notes, offered_by FROM claimed
+             RETURNING id`,
+            [email, userId]);
+        return result.rowCount ?? 0;
+    }
+
     private async upsertDefinition(appId : string | null, entitlementId : string, notes : string) : Promise<void> {
         await this.pool.query(
             `INSERT INTO entitlements (app_id, entitlement_id, notes)

package/src/hosting/HostingServer.ts

@@ -9,6 +9,8 @@ import {ConsumerRegistry} from "../queuing/ConsumerRegistry";
 import {AppProxyHandler} from "./handlers/AppProxyHandler";
 import {AppLinkFallbackHandler} from "./handlers/AppLinkFallbackHandler";
 import {AppsHandler} from "./handlers/AppsHandler";
+import {MyAppsHandler} from "./handlers/MyAppsHandler";
+import {Subdomains} from "../subdomains/Subdomains";
 import {AuditsHandler} from "./handlers/AuditsHandler";
 import {AuthorizeCliHandler} from "./handlers/auth/AuthorizeCliHandler";
 import {KeysHandler} from "./handlers/auth/KeysHandler";
@@ -74,7 +76,8 @@ class HostingServer {
                 userDirectory? : UserDirectory,
                 memberships? : MembershipService,
                 promptManagerFor? : (appId : string) => PromptManager,
-                fileStorageFor? : (appId : string) => FileStorage) {
+                fileStorageFor? : (appId : string) => FileStorage,
+                subdomains? : Subdomains) {
         const pages = new PagesHandler();
         const ping = new PingHandler(tenant);
         const jobs = new JobsHandler(persistence);
@@ -107,7 +110,7 @@ class HostingServer {
         if (notifier) publicRouter.registerApi("notifications", new NotificationsHandler(notifier));
         if (entitlements) publicRouter.registerApi("entitlements", new EntitlementsAdminHandler(entitlements));
         if (userDirectory) publicRouter.registerApi("users", new UsersHandler(userDirectory));
-        if (memberships) publicRouter.registerApi("invitations", new InvitationsHandler(memberships));
+        if (memberships) publicRouter.registerApi("invitations", new InvitationsHandler(memberships, entitlements));
         const prompts = promptManagerFor && new PromptsHandler(promptManagerFor);
         if (prompts) publicRouter.registerApi("prompts", prompts);
         if (cliAuthorizer) {
@@ -120,8 +123,15 @@ class HostingServer {
             // are wherever they registered themselves.
             buildLayer.consumerUrlsFor = appName =>
                 [...new Set(registry.list().filter(consumer => consumer.appId === appName).map(consumer => consumer.url))];
-            publicRouter.registerApi("apps", new AppsHandler(buildLayer, tenant));
+            buildLayer.appRemoved = appName => void subdomains?.release(appName);
+            publicRouter.registerApi("apps", new AppsHandler(buildLayer, tenant, subdomains));
             publicRouter.register("app", appProxy);
+
+            // The directory a person who is not a builder sees instead of the
+            // console, so it only exists where entitlements decide access.
+            if (entitlements) {
+                publicRouter.registerApi("my-apps", new MyAppsHandler(buildLayer, entitlements, subdomains));
+            }
         }
         // An unrouted absolute path carrying an app Referer is an app-internal
         // link the proxy's prefix-stripping left bare; send it back to its app.
@@ -151,10 +161,22 @@ class HostingServer {
             request.url.pathname === "/favicon.ico" ||
             (request.method === "GET" && CLI_KEY_POLL.test(request.url.pathname));
 
+        const authentication =
+            new AuthenticationMiddleware(authenticator, tokenAuthenticator, openRequests, undefined, userDirectory, memberships);
+
+        /* Entitlements an inviter chose before this person had a user id were
+           put aside under their email address; their first sign-in is when
+           they can finally be granted. */
+        if (entitlements) {
+            authentication.claimWhatIsOwed = async user => {
+                if (user.email) await entitlements.claim(user.email, user.id);
+            };
+        }
+
         this.publicServer = new Server(publicRouter, [
             new SessionMiddleware(),
             new TenantRoutingMiddleware(tenant),
-            new AuthenticationMiddleware(authenticator, tokenAuthenticator, openRequests, undefined, userDirectory, memberships),
+            authentication,
             /* After authentication and before routing: an app reached by its own
                hostname owns every path on it, so nothing of the platform's would
                match anyway - but a nicer address must not also be a way in

package/src/hosting/handlers/AppsHandler.ts

@@ -2,11 +2,14 @@ import {BuildLayer} from "../../app-management/BuildLayer";
 import {deniesBuild} from "../../auth/TenantRole";
 import {Request} from "../Request";
 import {hostnameObjection} from "../../app-management/appHostname";
+import {appAddress} from "../../app-management/appAddress";
 import {RequestHandler} from "../RequestHandler";
+import {Subdomains} from "../../subdomains/Subdomains";
 
 class AppsHandler implements RequestHandler {
 
-    constructor(private buildLayer : BuildLayer, private tenant? : string) {}
+    constructor(private buildLayer : BuildLayer, private tenant? : string,
+                private subdomains? : Subdomains) {}
 
     async handle(request : Request) : Promise<void> {
         // Changing what is deployed is a builder's job; a USER may look.
@@ -25,6 +28,9 @@ class AppsHandler implements RequestHandler {
             case "docs":
                 if (request.id) return this.handleDocs(request, request.id);
                 break;
+            case "subdomain":
+                if (request.id) return this.handleSubdomain(request, request.id);
+                break;
             case undefined:
                 if (request.id) return this.handleApp(request, request.id);
                 return this.handleCollection(request);
@@ -34,9 +40,30 @@ class AppsHandler implements RequestHandler {
 
     private changesApps(request : Request) : boolean {
         if (request.subresource === "deploy" || request.subresource === "docs") return true;
+        if (request.subresource === "subdomain") return request.method === "PUT";
         return request.subresource === undefined && request.method === "DELETE";
     }
 
+    /* Where an app answers, which is a builder's to change. The address itself
+       is the control plane's to agree, so a name already taken comes back from
+       there as a refusal and is passed on as one. */
+    private async handleSubdomain(request : Request, appName : string) : Promise<void> {
+        if (request.method !== "PUT") return request.notFound();
+        if (! this.subdomains) {
+            return request.reply(409, { error: "This platform does not give its apps addresses of their own" });
+        }
+        if (! this.buildLayer.status(appName)) return request.reply(404, { error: `No app named "${appName}"` });
+
+        const body = await request.body() as { subdomain? : string } | undefined;
+        const wanted = String(body?.subdomain ?? "").trim().toLowerCase();
+
+        try {
+            return request.reply(200, await this.subdomains.set(appName, wanted));
+        } catch (error) {
+            return request.reply(409, { error: error instanceof Error ? error.message : "That address is not available" });
+        }
+    }
+
     private async handleDocs(request : Request, appName : string) : Promise<void> {
         if (request.method !== "POST") return request.notFound();
         try {
@@ -55,7 +82,7 @@ class AppsHandler implements RequestHandler {
                    part of a hostname would deploy happily and then simply not
                    be reachable by its own address, which is a worse thing to
                    discover later. */
-                const objection = hostnameObjection(appName, this.tenant ?? "");
+                const objection = hostnameObjection(appName);
                 if (objection) return request.reply(400, { error: objection });
 
                 const appPort = Number(request.query("port"));
@@ -64,7 +91,19 @@ class AppsHandler implements RequestHandler {
                 }
                 const tarball = await request.rawBody();
                 if (tarball.length === 0) return request.reply(400, { error: "Expected a gzipped tarball body" });
-                return request.reply(202, this.buildLayer.deploy(appName, appPort, tarball));
+
+                const summary = this.buildLayer.deploy(appName, appPort, tarball);
+
+                /* An address is asked for alongside the build rather than
+                   after it: allocation is idempotent, so a redeploy costs
+                   nothing, and a first deploy has its address ready by the
+                   time the app is up. */
+                const address = await this.subdomains?.allocate(appName);
+                return request.reply(202, {
+                    ...summary,
+                    subdomain: address?.subdomain,
+                    url: appAddress(appName, address?.subdomain),
+                });
             }
         }
         request.notFound();
@@ -76,11 +115,15 @@ class AppsHandler implements RequestHandler {
                 const status = this.buildLayer.status(appName);
                 if (!status) return request.reply(404, { error: `No app named "${appName}"` });
                 const live = await this.buildLayer.ping(appName);
-                return request.reply(200, { ...status, live });
+                const subdomain = await this.addressOf(appName);
+                return request.reply(200, { ...status, live, subdomain, url: appAddress(appName, subdomain) });
             }
             case "DELETE": {
                 const outcome = await this.buildLayer.teardown(appName);
                 if (!outcome) return request.reply(404, { error: `No app named "${appName}"` });
+
+                // The address is let go by the build layer's appRemoved hook,
+                // which an app that drains reaches minutes after this returns.
                 return request.reply(200, outcome);
             }
         }
@@ -129,12 +172,28 @@ class AppsHandler implements RequestHandler {
 
     private async handleCollection(request : Request) : Promise<void> {
         switch (request.method) {
-            case "GET":
-                return request.reply(200, this.buildLayer.list());
+            case "GET": {
+                const addresses = new Map((await this.addresses()).map(held => [held.appName, held.subdomain]));
+                return request.reply(200, this.buildLayer.list().map(app => {
+                    const subdomain = addresses.get(app.appName);
+                    return { ...app, subdomain, url: appAddress(app.appName, subdomain) };
+                }));
+            }
         }
         request.notFound();
     }
 
+    private async addressOf(appName : string) : Promise<string | undefined> {
+        return (await this.addresses()).find(held => held.appName === appName)?.subdomain;
+    }
+
+    /* An address is the control plane's to know, so a platform without one -
+       self-hosted, or local - simply has none, and the console falls back to
+       serving its apps by path. */
+    private async addresses() {
+        return this.subdomains ? this.subdomains.all() : [];
+    }
+
 }
 
 export { AppsHandler }

package/src/hosting/handlers/MyAppsHandler.ts

@@ -0,0 +1,48 @@
+import {BuildLayer} from "../../app-management/BuildLayer";
+import {appAddress} from "../../app-management/appAddress";
+import {EntitlementStore} from "../../data-store/EntitlementStore";
+import {Subdomains} from "../../subdomains/Subdomains";
+import {Request} from "../Request";
+import {RequestHandler} from "../RequestHandler";
+
+/* The entitlement that says a person may open an app at all. The platform
+   seeds it as a global definition, so it exists in every tenant from the first
+   migration and nobody has to create it. Granted globally it means every app;
+   granted against one app it means that app. */
+const ACCESS = "access";
+
+/* The apps this person may open, which is what the directory shows someone who
+   is not a builder. The same question Entitlements.has answers one app at a
+   time, asked once for the whole list. */
+class MyAppsHandler implements RequestHandler {
+
+    constructor(private buildLayer : BuildLayer, private entitlements : EntitlementStore,
+                private subdomains? : Subdomains) {}
+
+    async handle(request : Request) : Promise<void> {
+        if (request.method !== "GET" || request.id) return request.notFound();
+        if (! request.user) return request.reply(401, { error: "You are not signed in" });
+
+        await this.buildLayer.ensureHydrated();
+
+        const grants = (await this.entitlements.listGrants(request.user.id))
+            .filter(grant => grant.entitlementId === ACCESS);
+        const everyApp = grants.some(grant => grant.appId === null);
+        const named = new Set(grants.map(grant => grant.appId));
+
+        const addresses = new Map(
+            (this.subdomains ? await this.subdomains.all() : []).map(held => [held.appName, held.subdomain]));
+
+        request.reply(200, this.buildLayer.list()
+            .filter(app => everyApp || named.has(app.appName))
+            .map(app => ({
+                appName: app.appName,
+                status: app.status,
+                subdomain: addresses.get(app.appName),
+                url: appAddress(app.appName, addresses.get(app.appName)),
+            })));
+    }
+
+}
+
+export { MyAppsHandler, ACCESS };