@jimhoyd/urlcode-admin 0.1.0-alpha.1

package/dist/scaffold.js

@@ -0,0 +1,46 @@
+import { readFile, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { initAuthentication } from '@jimhoyd/urlcode-auth';
+const readme = `## Administration
+
+The admin extension shares auth's operator service, CSRF key and explicit project revision. Its host entry references the \`service\`, \`csrfKey\` and \`projectSha256\` identifiers that auth's host setup defines; admin adds no key files, database or environment variables of its own. After bootstrapping and signing in as the first administrator, open /admin. Public registration is off. User invitations, account setup mail and impersonation require explicit sender callbacks; impersonation is disabled by default. Do not put operator modules or data/ into the app directory.`;
+/** Describes admin's contribution to a composed project without writing anything. Requires the auth extension in the same host. */
+export async function scaffold(request) {
+    for (const key of ['directory', 'project', 'hostFile'])
+        if (typeof request[key] !== 'string' || !request[key])
+            throw new Error(`Scaffold request needs an absolute ${key}`);
+    if (!request.names.includes('auth'))
+        throw new Error("Admin scaffold requires the auth extension: urlcode init --with auth,admin");
+    return {
+        name: 'admin',
+        extensions: { admin: { version: '1', config: {} } },
+        routes: { '/admin/*': { extension: 'admin', methods: ['GET', 'HEAD', 'POST'] } },
+        hostImports: ["import {adminExtension} from '@jimhoyd/urlcode-admin';"],
+        hostSetup: ['// Admin reuses service, csrfKey and projectSha256 from the auth setup above.'],
+        hostEntries: ["adminExtension({service, csrfKey, projectSha256, authMount: '/account'})"],
+        files: [],
+        readme,
+        nextSteps: ['Bootstrap the first administrator with `npx urlcode-auth bootstrap`, sign in at /account/login, then open /admin.', 'Configure sender callbacks before inviting users; impersonation stays disabled until explicitly enabled.'],
+    };
+}
+/** Separate operator host and route project; both extensions remain explicitly pinned. */
+export async function initAdministration(directory) {
+    const created = await initAuthentication(directory);
+    try {
+        const admin = await scaffold({ directory: created.directory, project: created.project, hostFile: created.hostFile, names: ['auth', 'admin'] });
+        const document = { version: '1', extensions: { auth: { version: '1', config: { registration: 'off' } }, ...admin.extensions }, routes: { '/account/*': { extension: 'auth', methods: ['GET', 'HEAD', 'POST'] }, ...admin.routes, '/private': { respond: { text: 'Signed in' }, policies: { extensions: { auth: {} } } } } };
+        await writeFile(join(created.project, 'urlcode.yaml'), JSON.stringify(document, null, 2) + '\n');
+        const host = await readFile(created.hostFile, 'utf8');
+        const marker = 'extensions: [authExtension({service, csrfKey, projectSha256})]';
+        if (!host.includes(marker))
+            throw new Error('Incompatible auth scaffold');
+        await writeFile(created.hostFile, admin.hostImports.join('\n') + '\n' + host.replace(marker, `extensions: [authExtension({service, csrfKey, projectSha256}), ${admin.hostEntries.join(', ')}]`));
+        const instructions = await readFile(join(created.directory, 'README.md'), 'utf8');
+        await writeFile(join(created.directory, 'README.md'), instructions.replace('This starter includes auth only.', 'This starter includes auth and admin.').replace('/absolute/path/to/urlcode-auth', '/absolute/path/to/urlcode-auth /absolute/path/to/urlcode-admin') + '\n' + admin.readme + '\n');
+        return created;
+    }
+    catch (error) {
+        await rm(created.directory, { recursive: true, force: true });
+        throw error;
+    }
+}

package/dist/support-banner.d.ts

@@ -0,0 +1,11 @@
+import type { Runtime } from '@jimhoyd/urlcode';
+import type { AuthService } from '@jimhoyd/urlcode-auth';
+export interface SupportBannerOptions {
+    service: Pick<AuthService, 'authenticate'>;
+    authMount?: string;
+    message?: string;
+    endLabel?: string;
+    maximumHtmlBytes?: number;
+}
+/** Required host integration for impersonation: route every response through this runtime wrapper. */
+export declare function withSupportBanner(runtime: Runtime, options: SupportBannerOptions): Runtime;

package/dist/support-banner.js

@@ -0,0 +1,43 @@
+import { escapeHtml } from '@jimhoyd/urlcode-ui';
+/** Required host integration for impersonation: route every response through this runtime wrapper. */
+export function withSupportBanner(runtime, options) {
+    const mount = options.authMount ?? '/account', maximum = options.maximumHtmlBytes ?? 1048576;
+    if (!/^\/[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(mount) || !Number.isSafeInteger(maximum) || maximum < 1024 || maximum > 4194304)
+        throw new Error('Invalid support banner configuration');
+    for (const value of [options.message, options.endLabel])
+        if (value !== undefined && (typeof value !== 'string' || !value || value.length > 512 || /[\x00-\x1f\x7f]/.test(value)))
+            throw new Error('Invalid support banner copy');
+    const banner = `<aside role="alert" aria-label="Support session" id="urlcode-support-banner"><strong>${escapeHtml(options.message ?? 'Support impersonation is active. Security changes are disabled.')}</strong> <a href="${escapeHtml(mount + '/account')}">${escapeHtml(options.endLabel ?? 'End support session')}</a></aside>`;
+    const handle = async (request) => {
+        const requestHeaders = new Headers(request.headers);
+        const cookies = requestHeaders.get('cookie') ?? '', candidates = cookies.split(';').map(value => value.trim()).filter(value => value.startsWith('__Host-urlcode-session='));
+        const token = cookies.length <= 8192 && candidates.length === 1 && (request.headerCounts?.cookie ?? 1) === 1 ? candidates[0].slice('__Host-urlcode-session='.length) : '';
+        const principal = /^[A-Za-z0-9_-]{43}$/.test(token) ? await options.service.authenticate(token) : null;
+        if (!principal?.impersonatorId)
+            return runtime.handle({ ...request, headers: requestHeaders });
+        const headers = new Headers(requestHeaders);
+        for (const name of ['if-none-match', 'if-modified-since', 'range', 'if-range', 'accept-encoding'])
+            headers.delete(name);
+        const result = await runtime.handle({ ...request, headers });
+        const output = result.headers.filter(([name]) => !['cache-control', 'cdn-cache-control', 'vercel-cdn-cache-control', 'surrogate-control', 'etag', 'last-modified', 'content-length', 'x-urlcode-support-session'].includes(name.toLowerCase()));
+        output.push(['cache-control', 'no-store'], ['cdn-cache-control', 'no-store'], ['x-urlcode-support-session', 'active']);
+        const type = output.find(([name]) => name.toLowerCase() === 'content-type')?.[1].split(';')[0]?.trim().toLowerCase();
+        if (result.status !== 304 && (request.method?.toUpperCase() === 'HEAD' || type !== 'text/html' || result.status < 200 || result.status === 204 || result.status >= 300 && result.status < 400))
+            return { ...result, headers: output };
+        const encoded = typeof result.body === 'string' ? Buffer.from(result.body) : Buffer.from(result.body ?? new Uint8Array());
+        let html;
+        try {
+            if (result.status === 304 || output.filter(([name]) => name.toLowerCase() === 'content-type').length !== 1 || encoded.byteLength > maximum || output.some(([name, value]) => name.toLowerCase() === 'content-encoding' && value !== 'identity'))
+                throw new Error('Unsupported response');
+            html = new TextDecoder('utf-8', { fatal: true }).decode(encoded);
+        }
+        catch {
+            return { status: 409, headers: [['content-type', 'text/html; charset=utf-8'], ['cache-control', 'no-store'], ['cdn-cache-control', 'no-store'], ['x-urlcode-support-session', 'active'], ['content-security-policy', "default-src 'none'; base-uri 'none'; frame-ancestors 'none'"], ['referrer-policy', 'no-referrer'], ['x-content-type-options', 'nosniff']], body: `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Support session</title></head><body>${banner}<p>This page cannot be displayed safely during a support session.</p></body></html>` };
+        }
+        html = /<body(?:\s[^>]*)?>/i.test(html) ? html.replace(/<body(?:\s[^>]*)?>/i, match => match + banner) : banner + html;
+        const { contentLength: _length, ...rest } = result;
+        return { ...rest, headers: output, body: new TextEncoder().encode(html) };
+    };
+    return new Proxy(runtime, { get(target, key) { if (key === 'handle')
+            return handle; const value = Reflect.get(target, key, target); return typeof value === 'function' ? value.bind(target) : value; } });
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@jimhoyd/urlcode-admin",
+  "version": "0.1.0-alpha.1",
+  "type": "module",
+  "description": "Administration console extension for URLCode, on top of the auth extension",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jimhoyd-com/urlcode-admin.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "pretest": "node scripts/check-sqlite.mjs",
+    "test": "node --conditions=development --test test/*.test.ts",
+    "verify": "npm run typecheck && npm run build && npm test"
+  },
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "IMPLEMENTATION-STATUS.md",
+    "THREAT-MODEL.md",
+    "UX-REVIEW.md"
+  ],
+  "devDependencies": {
+    "@types/node": "26.5.1",
+    "typescript": "6.0.3"
+  },
+  "peerDependencies": {
+    "@jimhoyd/urlcode": ">=0.4.0-alpha.1 <0.5.0",
+    "@jimhoyd/urlcode-auth": ">=0.1.0-alpha.2 <0.2.0",
+    "@jimhoyd/urlcode-ui": ">=0.1.0-alpha.1 <0.2.0"
+  },
+  "bin": {
+    "urlcode-admin": "./dist/cli.js"
+  },
+  "homepage": "https://github.com/jimhoyd-com/urlcode-admin#readme",
+  "bugs": {
+    "url": "https://github.com/jimhoyd-com/urlcode-admin/issues"
+  }
+}