anbaric-cloud-hosting 1.31.0 → 1.33.0

package/package.json

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

package/src/app-management/BaseBuildLayer.ts

@@ -114,10 +114,28 @@ abstract class BaseBuildLayer implements BuildLayer {
         }));
     }
 
+    // Regenerates an app's docs from its uploaded source without redeploying it:
+    // the source is materialised (from S3 for Fargate, from disk for Docker) and
+    // the same generator that runs on deploy is invoked against it.
+    async regenerateDocs(appName : string) : Promise<number> {
+        if (!this.deployments.has(appName)) throw new Error(`No app named "${appName}"`);
+        if (!this.docGenerator) throw new Error("Documentation generation is not configured on this platform");
+
+        const { dir, cleanup } = await this.sourceDir(appName);
+        try {
+            return await this.docGenerator.generate(appName, dir, { redeploy: true });
+        } finally {
+            await cleanup();
+        }
+    }
+
     protected abstract appHostFor(appName : string) : string;
     protected abstract start(deployment : Deployment, appDir : string, entryPoint : string) : Promise<void>;
     protected abstract stop(deployment : Deployment) : Promise<void>;
     protected abstract streamLogs(deployment : Deployment, signal : AbortSignal) : AsyncIterable<string>;
+    // Materialises the app's source into a directory for regeneration; the
+    // returned cleanup removes anything temporary the implementation created.
+    protected abstract sourceDir(appName : string) : Promise<{ dir : string, cleanup : () => Promise<void> }>;
 
     private async buildAndStart(deployment : Deployment, tarball : Buffer) : Promise<void> {
         const appDir = join(this.appsDir, deployment.appName);

package/src/app-management/BuildLayer.ts

@@ -16,6 +16,9 @@ interface BuildLayer {
     ping(appName : string) : Promise<boolean>;
     logs(appName : string, signal : AbortSignal) : AsyncIterable<string>;
     teardown(appName : string) : Promise<boolean>;
+    // Re-runs documentation generation for an already-deployed app from its
+    // uploaded source, without redeploying it. Returns the number of docs written.
+    regenerateDocs(appName : string) : Promise<number>;
     cleanUp() : Promise<void>;
 
 }

package/src/app-management/DockerBuildLayer.ts

@@ -107,6 +107,7 @@ class DockerBuildLayer extends BaseBuildLayer {
             "--env", "ANBARIC_SECRET_STORE_TYPE=cloud",
             "--env", "ANBARIC_AUDITOR_TYPE=cloud",
             "--env", "ANBARIC_SESSION_RESOLVER_TYPE=cloud",
+            "--env", "ANBARIC_ENTITLEMENTS_TYPE=cloud",
             "--env", "ANBARIC_NOTIFIER_TYPE=cloud",
             "--env", `ANBARIC_CONSUMER_PORT=${deployment.consumerPort}`,
             "--env", `ANBARIC_CONSUMER_URL=http://${container}:${deployment.consumerPort}`,
@@ -120,6 +121,12 @@ class DockerBuildLayer extends BaseBuildLayer {
         await this.removeContainer(deployment, this.appHostFor(deployment.appName));
     }
 
+    // Locally the extracted source from the last deploy is still on disk, so
+    // regeneration reads it in place with nothing to clean up.
+    protected async sourceDir(appName : string) : Promise<{ dir : string, cleanup : () => Promise<void> }> {
+        return { dir: join(this.appsDir, appName), cleanup: async () => {} };
+    }
+
     private async removeContainer(deployment : Deployment, container : string) : Promise<void> {
         await this.docker(deployment, ["rm", "--force", container]).catch(() => {});
     }

package/src/app-management/FargateBuildLayer.ts

@@ -1,10 +1,12 @@
-import {readFile, writeFile} from "node:fs/promises";
+import {spawn} from "node:child_process";
+import {mkdir, mkdtemp, readFile, rm, writeFile} from "node:fs/promises";
+import {tmpdir} from "node:os";
 import {join} from "node:path";
 import {CodeBuildClient, BatchGetBuildsCommand, StartBuildCommand} from "@aws-sdk/client-codebuild";
 import {ECSClient, CreateServiceCommand, DeleteServiceCommand, DescribeServicesCommand,
     DescribeTaskDefinitionCommand, ListServicesCommand as ListEcsServicesCommand,
     RegisterTaskDefinitionCommand, UpdateServiceCommand} from "@aws-sdk/client-ecs";
-import {S3Client, PutObjectCommand} from "@aws-sdk/client-s3";
+import {S3Client, GetObjectCommand, PutObjectCommand} from "@aws-sdk/client-s3";
 import {ServiceDiscoveryClient, CreateServiceCommand as CreateDiscoveryServiceCommand,
     ListServicesCommand} from "@aws-sdk/client-servicediscovery";
 import {CloudWatchLogsClient, FilterLogEventsCommand, StartLiveTailCommand} from "@aws-sdk/client-cloudwatch-logs";
@@ -195,6 +197,7 @@ class FargateBuildLayer extends BaseBuildLayer {
                     { name: "ANBARIC_SECRET_STORE_TYPE", value: "cloud" },
                     { name: "ANBARIC_AUDITOR_TYPE", value: "cloud" },
                     { name: "ANBARIC_SESSION_RESOLVER_TYPE", value: "cloud" },
+                    { name: "ANBARIC_ENTITLEMENTS_TYPE", value: "cloud" },
                     { name: "ANBARIC_NOTIFIER_TYPE", value: "cloud" },
                     { name: "ANBARIC_CONSUMER_PORT", value: String(deployment.consumerPort) },
                     { name: "ANBARIC_CONSUMER_URL", value: `http://${deployment.appHost}:${deployment.consumerPort}` },
@@ -344,7 +347,38 @@ class FargateBuildLayer extends BaseBuildLayer {
         return `builds/${appName}.tar.gz`;
     }
 
+    protected async sourceDir(appName : string) : Promise<{ dir : string, cleanup : () => Promise<void> }> {
+        const work = await mkdtemp(join(tmpdir(), `anbaric-docs-${appName}-`));
+        const cleanup = () => rm(work, { recursive: true, force: true });
+
+        try {
+            const object = await this.aws.s3.send(new GetObjectCommand({
+                Bucket: this.options.buildBucket,
+                Key: this.buildKeyFor(appName),
+            }));
+            const bytes = await object.Body.transformToByteArray();
+
+            const tarballPath = join(work, "source.tar.gz");
+            await writeFile(tarballPath, Buffer.from(bytes));
+            const dir = join(work, "src");
+            await mkdir(dir, { recursive: true });
+            await extractTarball(tarballPath, dir);
+
+            return { dir, cleanup };
+        } catch (error) {
+            await cleanup();
+            throw error;
+        }
+    }
+
 }
 
+const extractTarball = (tarballPath : string, dir : string) : Promise<void> =>
+    new Promise((resolve, reject) => {
+        const tar = spawn("tar", ["-xzf", tarballPath, "-C", dir]);
+        tar.on("error", reject);
+        tar.on("close", code => code === 0 ? resolve() : reject(new Error(`tar exited with code ${code}`)));
+    });
+
 export { FargateBuildLayer };
 export type { AwsClients, FargateBuildLayerOptions };

package/src/data-store/EntitlementStore.ts

@@ -0,0 +1,41 @@
+import {Entitlements} from "anbaric-tsapi";
+
+/* An appId of null means global: a global definition is one no app owns
+   (console-created), a global grant satisfies the check from any app. */
+type EntitlementDefinition = {
+
+    appId : string | null,
+    entitlementId : string,
+    notes : string,
+
+};
+
+type EntitlementGrant = {
+
+    id : string,
+    userId : string,
+    appId : string | null,
+    entitlementId : string,
+    notes : string,
+    grantedAt : string,
+    grantedBy : 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 {
+
+    defineGlobal(entitlementId : string, notes : string) : Promise<void>;
+
+    listDefinitions() : Promise<Array<EntitlementDefinition>>;
+
+    grant(userId : string, appId : string | null, entitlementId : string, notes : string, grantedBy : string) : Promise<EntitlementGrant>;
+
+    revoke(grantId : string) : Promise<boolean>;
+
+    listGrants(userId? : string) : Promise<Array<EntitlementGrant>>;
+
+}
+
+export type { EntitlementStore, EntitlementDefinition, EntitlementGrant }

package/src/data-store/InMemoryEntitlementStore.ts

@@ -0,0 +1,55 @@
+import {randomUUID} from "node:crypto";
+import {EntitlementDefinition, EntitlementGrant, EntitlementStore} from "./EntitlementStore";
+
+class InMemoryEntitlementStore implements EntitlementStore {
+
+    private definitions = new Map<string, EntitlementDefinition>();
+    private grants = new Map<string, EntitlementGrant>();
+
+    constructor() {
+        this.definitions.set(this.key(null, "access"), { appId: null, entitlementId: "access", notes: "Global access" });
+    }
+
+    async register(appId : string, entitlementId : string, notes : string = "") : Promise<void> {
+        this.definitions.set(this.key(appId, entitlementId), { appId, entitlementId, notes });
+    }
+
+    async has(appId : string, userId : string, entitlementId : string) : Promise<boolean> {
+        return Array.from(this.grants.values()).some(grant =>
+            grant.userId === userId && grant.entitlementId === entitlementId &&
+            (grant.appId === null || grant.appId === appId));
+    }
+
+    async defineGlobal(entitlementId : string, notes : string) : Promise<void> {
+        this.definitions.set(this.key(null, entitlementId), { appId: null, entitlementId, notes });
+    }
+
+    async listDefinitions() : Promise<Array<EntitlementDefinition>> {
+        return Array.from(this.definitions.values()).map(definition => ({ ...definition }));
+    }
+
+    async grant(userId : string, appId : string | null, entitlementId : string, notes : string, grantedBy : string) : Promise<EntitlementGrant> {
+        const grant : EntitlementGrant = {
+            id: randomUUID(), userId, appId, entitlementId, notes, grantedBy, grantedAt: new Date().toISOString(),
+        };
+        this.grants.set(grant.id, grant);
+        return { ...grant };
+    }
+
+    async revoke(grantId : string) : Promise<boolean> {
+        return this.grants.delete(grantId);
+    }
+
+    async listGrants(userId? : string) : Promise<Array<EntitlementGrant>> {
+        return Array.from(this.grants.values())
+            .filter(grant => userId === undefined || grant.userId === userId)
+            .map(grant => ({ ...grant }));
+    }
+
+    private key(appId : string | null, entitlementId : string) : string {
+        return `${appId ?? ""}/${entitlementId}`;
+    }
+
+}
+
+export { InMemoryEntitlementStore }

package/src/data-store/PostgresEntitlementStore.ts

@@ -0,0 +1,81 @@
+import {randomUUID} from "node:crypto";
+import {Pool} from "pg";
+import {EntitlementDefinition, EntitlementGrant, EntitlementStore} from "./EntitlementStore";
+
+class PostgresEntitlementStore implements EntitlementStore {
+
+    constructor(private pool : Pool) {}
+
+    async register(appId : string, entitlementId : string, notes : string = "") : Promise<void> {
+        await this.upsertDefinition(appId, entitlementId, notes);
+    }
+
+    async has(appId : string, userId : string, entitlementId : string) : Promise<boolean> {
+        const result = await this.pool.query(
+            `SELECT 1 FROM entitlement_grants
+             WHERE user_id = $1 AND entitlement_id = $2 AND (app_id = $3 OR app_id IS NULL)
+             LIMIT 1`,
+            [userId, entitlementId, appId]);
+        return (result.rowCount ?? 0) > 0;
+    }
+
+    async defineGlobal(entitlementId : string, notes : string) : Promise<void> {
+        await this.upsertDefinition(null, entitlementId, notes);
+    }
+
+    async listDefinitions() : Promise<Array<EntitlementDefinition>> {
+        const result = await this.pool.query(
+            `SELECT app_id, entitlement_id, notes FROM entitlements
+             ORDER BY app_id NULLS FIRST, entitlement_id`);
+        return result.rows.map(row => ({ appId: row.app_id, entitlementId: row.entitlement_id, notes: row.notes }));
+    }
+
+    async grant(userId : string, appId : string | null, entitlementId : string, notes : string, grantedBy : string) : Promise<EntitlementGrant> {
+        const id = randomUUID();
+        const result = await this.pool.query(
+            `INSERT INTO entitlement_grants (id, user_id, app_id, entitlement_id, notes, granted_by)
+             VALUES ($1, $2, $3, $4, $5, $6)
+             RETURNING granted_at`,
+            [id, userId, appId, entitlementId, notes, grantedBy]);
+        return { id, userId, appId, entitlementId, notes, grantedBy, grantedAt: this.iso(result.rows[0]?.granted_at) };
+    }
+
+    async revoke(grantId : string) : Promise<boolean> {
+        const result = await this.pool.query("DELETE FROM entitlement_grants WHERE id = $1", [grantId]);
+        return (result.rowCount ?? 0) > 0;
+    }
+
+    async listGrants(userId? : string) : Promise<Array<EntitlementGrant>> {
+        const result = userId === undefined
+            ? await this.pool.query(
+                `SELECT id, user_id, app_id, entitlement_id, notes, granted_at, granted_by
+                 FROM entitlement_grants ORDER BY granted_at DESC`)
+            : await this.pool.query(
+                `SELECT id, user_id, app_id, entitlement_id, notes, granted_at, granted_by
+                 FROM entitlement_grants WHERE user_id = $1 ORDER BY granted_at DESC`, [userId]);
+        return result.rows.map(row => ({
+            id: row.id,
+            userId: row.user_id,
+            appId: row.app_id,
+            entitlementId: row.entitlement_id,
+            notes: row.notes,
+            grantedAt: this.iso(row.granted_at),
+            grantedBy: row.granted_by,
+        }));
+    }
+
+    private async upsertDefinition(appId : string | null, entitlementId : string, notes : string) : Promise<void> {
+        await this.pool.query(
+            `INSERT INTO entitlements (app_id, entitlement_id, notes)
+             VALUES ($1, $2, $3)
+             ON CONFLICT (COALESCE(app_id, ''), entitlement_id) DO UPDATE SET notes = EXCLUDED.notes`,
+            [appId, entitlementId, notes]);
+    }
+
+    private iso(value : unknown) : string {
+        return value instanceof Date ? value.toISOString() : String(value ?? new Date().toISOString());
+    }
+
+}
+
+export { PostgresEntitlementStore }

package/src/data-store/Schema.ts

@@ -112,6 +112,38 @@ const ensureSchema = async (pool : Pool) : Promise<void> => {
     `);
     await pool.query("ALTER TABLE app_docs ADD COLUMN IF NOT EXISTS parent_slug TEXT");
     await pool.query("ALTER TABLE app_docs ADD COLUMN IF NOT EXISTS position INTEGER NOT NULL DEFAULT 0");
+    await pool.query(`
+        CREATE TABLE IF NOT EXISTS entitlements (
+            app_id          TEXT,
+            entitlement_id  TEXT NOT NULL,
+            notes           TEXT NOT NULL DEFAULT '',
+            registered_at   TIMESTAMPTZ NOT NULL DEFAULT now()
+        )
+    `);
+    await pool.query(`
+        CREATE UNIQUE INDEX IF NOT EXISTS entitlements_key
+        ON entitlements (COALESCE(app_id, ''), entitlement_id)
+    `);
+    await pool.query(`
+        CREATE TABLE IF NOT EXISTS entitlement_grants (
+            id              TEXT PRIMARY KEY,
+            user_id         TEXT NOT NULL,
+            app_id          TEXT,
+            entitlement_id  TEXT NOT NULL,
+            notes           TEXT NOT NULL DEFAULT '',
+            granted_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+            granted_by      TEXT NOT NULL
+        )
+    `);
+    await pool.query(`
+        CREATE INDEX IF NOT EXISTS entitlement_grants_lookup
+        ON entitlement_grants (user_id, entitlement_id)
+    `);
+    await pool.query(`
+        INSERT INTO entitlements (app_id, entitlement_id, notes)
+        VALUES (NULL, 'access', 'Global access')
+        ON CONFLICT (COALESCE(app_id, ''), entitlement_id) DO NOTHING
+    `);
     await pool.query("CREATE SCHEMA IF NOT EXISTS anbaric_system");
     await pool.query(`
         CREATE TABLE IF NOT EXISTS anbaric_system.cli_keys (

package/src/docs/DocGenerator.ts

@@ -75,20 +75,22 @@ class DocGenerator {
 
     constructor(private model : DocModel, private store : AppDocsStore) {}
 
-    async generate(appName : string, appDir : string, options : { redeploy : boolean }) : Promise<void> {
+    async generate(appName : string, appDir : string, options : { redeploy : boolean }) : Promise<number> {
         try {
             const { files, truncated } = await gatherSources(appDir);
-            if (files.length === 0) return;
+            if (files.length === 0) return 0;
 
             const drafts = await this.model.writeDocs({ appName, files, truncated });
             const readme = files.find(file => README.test(file.path))?.content;
             const docs = buildDocTree(drafts, readme);
-            if (docs.length === 0) return;
+            if (docs.length === 0) return 0;
 
             await this.store.replaceForApp(appName, docs);
             console.log(`[docs] ${options.redeploy ? "regenerated" : "generated"} ${docs.length} doc(s) for "${appName}"`);
+            return docs.length;
         } catch (error) {
             console.error(`[docs] could not generate documentation for "${appName}": ${error instanceof Error ? error.message : error}`);
+            return 0;
         }
     }
 

package/src/hosting/HostingServer.ts

@@ -16,6 +16,9 @@ import {SessionsHandler} from "./handlers/auth/SessionsHandler";
 import {WhoamiHandler} from "./handlers/auth/WhoamiHandler";
 import {ConsumersHandler} from "./handlers/ConsumersHandler";
 import {DocumentsHandler} from "./handlers/DocumentsHandler";
+import {EntitlementsAdminHandler} from "./handlers/EntitlementsAdminHandler";
+import {EntitlementsHandler} from "./handlers/EntitlementsHandler";
+import {EntitlementStore} from "../data-store/EntitlementStore";
 import {JobsHandler} from "./handlers/JobsHandler";
 import {FaviconHandler} from "./handlers/FaviconHandler";
 import {JobRunSchedulesHandler} from "./handlers/JobRunSchedulesHandler";
@@ -58,7 +61,8 @@ class HostingServer {
                 auditRecords? : AuditRecordStore,
                 plugins : Array<LoadedPlugin> = [],
                 jobRunSchedules? : JobRunSchedulePersistence,
-                notifier? : Notifier) {
+                notifier? : Notifier,
+                entitlements? : EntitlementStore) {
         const pages = new PagesHandler();
         const ping = new PingHandler(tenant);
         const jobs = new JobsHandler(persistence);
@@ -87,6 +91,7 @@ class HostingServer {
         if (audits) publicRouter.registerApi("audits", audits);
         if (jobRunSchedules) publicRouter.registerApi("job-run-schedules", new JobRunSchedulesHandler(jobRunSchedules));
         if (notifier) publicRouter.registerApi("notifications", new NotificationsHandler(notifier));
+        if (entitlements) publicRouter.registerApi("entitlements", new EntitlementsAdminHandler(entitlements));
         if (cliAuthorizer) {
             publicRouter.register("authorize-cli", new AuthorizeCliHandler(cliAuthorizer, pages, tenant));
             publicRouter.registerApi("keys", new KeysHandler(cliAuthorizer));
@@ -111,6 +116,7 @@ class HostingServer {
         if (audits) internalRouter.registerApi("audits", audits);
         if (jobRunSchedules) internalRouter.registerApi("job-run-schedules", new JobRunSchedulesHandler(jobRunSchedules));
         if (notifier) internalRouter.registerApi("notifications", new NotificationsHandler(notifier));
+        if (entitlements) internalRouter.registerApi("entitlements", new EntitlementsHandler(entitlements));
 
         // The favicon is requested by the browser before anyone has signed in,
         // and by deployed apps' pages, so gating it behind a session would send

package/src/hosting/handlers/AppsHandler.ts

@@ -15,6 +15,9 @@ class AppsHandler implements RequestHandler {
             case "logs":
                 if (request.id) return this.handleLogs(request, request.id);
                 break;
+            case "docs":
+                if (request.id) return this.handleDocs(request, request.id);
+                break;
             case undefined:
                 if (request.id) return this.handleApp(request, request.id);
                 return this.handleCollection(request);
@@ -22,6 +25,17 @@ class AppsHandler implements RequestHandler {
         request.notFound();
     }
 
+    private async handleDocs(request : Request, appName : string) : Promise<void> {
+        if (request.method !== "POST") return request.notFound();
+        try {
+            const docs = await this.buildLayer.regenerateDocs(appName);
+            return request.reply(200, { appName, docs });
+        } catch (error) {
+            const message = error instanceof Error ? error.message : "Could not regenerate documentation";
+            return request.reply(message.startsWith("No app") ? 404 : 400, { error: message });
+        }
+    }
+
     private async handleDeploy(request : Request, appName : string) : Promise<void> {
         switch (request.method) {
             case "POST": {

package/src/hosting/handlers/EntitlementsAdminHandler.ts

@@ -0,0 +1,52 @@
+import {EntitlementStore} from "../../data-store/EntitlementStore";
+import {Request} from "../Request";
+import {RequestHandler} from "../RequestHandler";
+
+/* The console-facing side, served on the authenticated public entry point:
+   list definitions, create global ones, and grant or revoke entitlements to
+   users. Grants record who made them from the signed-in user. */
+class EntitlementsAdminHandler implements RequestHandler {
+
+    constructor(private store : EntitlementStore) {}
+
+    async handle(request : Request) : Promise<void> {
+        const { method, id, subresource } = request;
+
+        if (method === "GET" && ! id) return request.reply(200, await this.store.listDefinitions());
+        if (method === "POST" && id === "definitions" && ! subresource) return this.defineGlobal(request);
+        if (method === "GET" && id === "grants" && ! subresource) {
+            return request.reply(200, await this.store.listGrants(request.query("userId")));
+        }
+        if (method === "POST" && id === "grants" && ! subresource) return this.grant(request);
+        if (method === "DELETE" && id === "grants" && subresource) return this.revoke(request, subresource);
+        request.notFound();
+    }
+
+    private async defineGlobal(request : Request) : Promise<void> {
+        const body = await request.body() as { entitlementId? : string, notes? : string } | undefined;
+        if (! body?.entitlementId) return request.reply(400, { error: "entitlementId is required" });
+
+        await this.store.defineGlobal(body.entitlementId, body.notes ?? "");
+        request.reply(204);
+    }
+
+    private async grant(request : Request) : Promise<void> {
+        const body = await request.body() as
+            { userId? : string, appId? : string | null, entitlementId? : string, notes? : string } | undefined;
+        if (! body?.userId || ! body.entitlementId) {
+            return request.reply(400, { error: "userId and entitlementId are required" });
+        }
+
+        const grantedBy = request.user?.id ?? "system";
+        const grant = await this.store.grant(body.userId, body.appId || null, body.entitlementId, body.notes ?? "", grantedBy);
+        request.reply(201, grant);
+    }
+
+    private async revoke(request : Request, grantId : string) : Promise<void> {
+        const removed = await this.store.revoke(grantId);
+        removed ? request.reply(204) : request.notFound();
+    }
+
+}
+
+export { EntitlementsAdminHandler }

package/src/hosting/handlers/EntitlementsHandler.ts

@@ -0,0 +1,39 @@
+import {Entitlements} from "anbaric-tsapi";
+import {Request} from "../Request";
+import {RequestHandler} from "../RequestHandler";
+
+/* The app-facing side, served on the internal entry point: register an
+   entitlement and check whether a user holds it. Both are scoped to the
+   calling app (the ambient app header), so an app can neither define a global
+   entitlement nor check as another app. */
+class EntitlementsHandler implements RequestHandler {
+
+    constructor(private entitlements : Entitlements) {}
+
+    async handle(request : Request) : Promise<void> {
+        const appId = request.appId;
+        if (! appId) return request.reply(400, { error: "Missing the x-anbaric-app header" });
+
+        if (request.method === "POST" && ! request.id) return this.register(request, appId);
+        if (request.method === "GET" && request.id && request.subresource === "check") return this.check(request, appId);
+        request.notFound();
+    }
+
+    private async register(request : Request, appId : string) : Promise<void> {
+        const body = await request.body() as { entitlementId? : string, notes? : string } | undefined;
+        if (! body?.entitlementId) return request.reply(400, { error: "entitlementId is required" });
+
+        await this.entitlements.register(appId, body.entitlementId, body.notes ?? "");
+        request.reply(204);
+    }
+
+    private async check(request : Request, appId : string) : Promise<void> {
+        const userId = request.query("userId");
+        if (! userId) return request.reply(400, { error: "userId is required" });
+
+        request.reply(200, { has: await this.entitlements.has(appId, userId, request.id!) });
+    }
+
+}
+
+export { EntitlementsHandler }

package/src/index.ts

@@ -27,6 +27,11 @@ export * from "./data-store/PostgresJobRunSchedulePersistence";
 export * from "./data-store/AppDocsStore";
 export * from "./data-store/PostgresAppDocsStore";
 export * from "./data-store/InMemoryAppDocsStore";
+export * from "./data-store/EntitlementStore";
+export * from "./data-store/PostgresEntitlementStore";
+export * from "./data-store/InMemoryEntitlementStore";
+export * from "./hosting/handlers/EntitlementsHandler";
+export * from "./hosting/handlers/EntitlementsAdminHandler";
 export * from "./docs/DocModel";
 export * from "./docs/GatewayDocModel";
 export * from "./docs/DocGenerator";

package/src/main.ts

@@ -20,6 +20,7 @@ import {FargateBuildLayer} from "./app-management/FargateBuildLayer";
 import {DocGenerator} from "./docs/DocGenerator";
 import {GatewayDocModel} from "./docs/GatewayDocModel";
 import {PostgresAppDocsStore} from "./data-store/PostgresAppDocsStore";
+import {PostgresEntitlementStore} from "./data-store/PostgresEntitlementStore";
 import {ConsumerRegistry} from "./queuing/ConsumerRegistry";
 import {Dispatcher} from "./queuing/Dispatcher";
 import {HostingServer} from "./hosting/HostingServer";
@@ -94,7 +95,8 @@ const plugins = await new PluginLoader().load(process.env.ANBARIC_PLUGINS ?? "an
 const server = new HostingServer(new PostgresJobPersistence(pool), queue, registry, buildLayer,
     (appId, collection) => new PostgresJsonStore(pool, appId, collection), secretStoreFor, authenticator, cliAuthorizer,
     tokenAuthenticator, process.env.ANBARIC_TENANT, new PostgresAuditRecordStore(pool), plugins,
-    new PostgresJobRunSchedulePersistence(pool), await loadNotifier(process.env.ANBARIC_NOTIFIER_MODULE));
+    new PostgresJobRunSchedulePersistence(pool), await loadNotifier(process.env.ANBARIC_NOTIFIER_MODULE),
+    new PostgresEntitlementStore(pool));
 const port = await server.listen(hostingPort);
 const internal = await server.listenInternal(internalPort);