@steve31415/baselib 2.5.0 → 3.0.1

package/dist/auth.d.ts

@@ -3,11 +3,20 @@ import type { Logger } from './log-core.js';
 import { ServiceCaller, S2sOptions } from './s2s.js';
 export declare const DEFAULT_AUTH_URL = "https://auth.apps.snewman.net";
 export declare const SESSION_COOKIE = "pw_session";
+/** The `code` in a 403 JSON body when a signed-in user is refused by the
+ *  app's userAccess policy (as opposed to any other 403). */
+export declare const ACCESS_DENIED_CODE = "app_access_denied";
+/** A user's fleet role, assigned in auth2's users table. */
+export type UserRole = 'owner' | 'invited';
+/** Which signed-in users an app admits. 'owner' (the default): only the
+ *  fleet owner(s). 'invited': any active fleet user. */
+export type UserAccessPolicy = 'owner' | 'invited';
 export interface AuthedUser {
     type: 'user';
     email: string;
     name?: string;
     userId?: string;
+    role: UserRole;
 }
 export type Identity = AuthedUser | ServiceCaller;
 declare module 'hono' {
@@ -22,16 +31,20 @@ export interface RequireIdentityOptions extends S2sOptions {
     /** Injectable for tests (defaults to global fetch). */
     whoamiFetch?: typeof fetch;
     logger?: Logger;
-    /** Distinguishes API requests (401) from page requests (redirect).
-     *  Default: path starts with /api/ or client prefers JSON. */
+    /** Distinguishes API requests (401/403 JSON) from page requests (redirect
+     *  / denial page). Default: path starts with /api/ or client prefers JSON. */
     isApiRequest?: (c: Context) => boolean;
     cacheTtl?: {
         hitMs?: number;
         missMs?: number;
     };
+    /** Which signed-in users this app admits. Default 'owner': only users
+     *  whose auth2 role is owner. Pass 'invited' only for an app that is
+     *  multi-user by design, and say so in its SPEC. Applies to browser
+     *  sessions and the test bypass alike; service callers are governed by
+     *  grants, not by this. */
+    userAccess?: UserAccessPolicy;
 }
-export declare function requireIdentity(opts: RequireIdentityOptions): import("hono").MiddlewareHandler<any, string, {}, (Response & import("hono").TypedResponse<undefined, 302, "redirect">) | (Response & import("hono").TypedResponse<{
-    error: string;
-}, 401 | 403 | 429, "json">) | (Response & import("hono").TypedResponse<{
-    error: string;
-}, 503, "json">)>;
+/** The one place the policy is evaluated. */
+export declare function userAllowed(policy: UserAccessPolicy, user: Pick<AuthedUser, 'role'>): boolean;
+export declare function requireIdentity(opts: RequireIdentityOptions): import("hono").MiddlewareHandler<any, string, {}, Response>;

package/dist/auth.js

@@ -1,27 +1,49 @@
-// Identity middleware for consuming apps (design §3.4).
+// Identity middleware for consuming apps (design §3.4; per-app access:
+// ~/migration/research/per-app-access-design.md).
 //
 // Resolves who is calling, in order:
 //   1. Test bypass (AUTH_MODE=test): X-Test-S2S-Caller → service caller;
-//      X-Test-User header or TEST_USER env → user. Credential verification is
-//      bypassed; authorization (grants, app-level user checks) still runs.
+//      X-Test-User header or TEST_USER env → user, with the fleet role from
+//      X-Test-User-Role / TEST_USER_ROLE (default 'invited'). Credential
+//      verification is bypassed; authorization (grants, the userAccess
+//      policy, app-level checks) still runs.
 //   2. Authorization: Bearer → service-to-service OIDC (s2s.ts).
 //   3. pw_session cookie → whoami call to the auth service, cached
 //      in-instance (10 min hits / 30 s misses — the old-world numbers).
 //
+// Then the user-access policy: by default an app admits only users whose
+// auth2 role is 'owner'; `userAccess: 'invited'` admits any active fleet
+// user. Being on the fleet sign-in allowlist never grants access by itself,
+// so a port that forgets the question is closed, not open. Service callers
+// are governed by grants, not by this policy.
+//
 // Unauthenticated: APIs get 401 JSON, pages redirect to the auth service's
-// login with a return URL. Auth-service *failures* (network, 5xx) return 503
-// and never redirect — a redirect on failure loops forever (old-world lesson).
+// login with a return URL. Denied users get 403 (JSON with a stable `code`
+// on APIs, a plain "not enabled" page otherwise). Auth-service *failures*
+// (network, 5xx, a whoami answer with no role) return 503 and never
+// redirect — a redirect on failure loops forever (old-world lesson).
 import { createHash } from 'node:crypto';
 import { createMiddleware } from 'hono/factory';
 import { authMode } from './config.js';
 import { RateLimiter, resolveS2sCaller } from './s2s.js';
 export const DEFAULT_AUTH_URL = 'https://auth.apps.snewman.net';
 export const SESSION_COOKIE = 'pw_session';
+/** The `code` in a 403 JSON body when a signed-in user is refused by the
+ *  app's userAccess policy (as opposed to any other 403). */
+export const ACCESS_DENIED_CODE = 'app_access_denied';
+/** The one place the policy is evaluated. */
+export function userAllowed(policy, user) {
+    return policy === 'invited' || user.role === 'owner';
+}
+function parseRole(value) {
+    return value === 'owner' || value === 'invited' ? value : undefined;
+}
 export function requireIdentity(opts) {
     const authUrl = (opts.authUrl ?? DEFAULT_AUTH_URL).replace(/\/$/, '');
     const whoamiFetch = opts.whoamiFetch ?? fetch;
     const hitMs = opts.cacheTtl?.hitMs ?? 600_000;
     const missMs = opts.cacheTtl?.missMs ?? 30_000;
+    const policy = opts.userAccess ?? 'owner';
     const limiter = new RateLimiter(opts.rateLimitPerMin ?? 600);
     const cache = new Map();
     const isApi = opts.isApiRequest ??
@@ -37,17 +59,33 @@ export function requireIdentity(opts) {
         }
         return c.redirect(`${authUrl}/login?redirect=${encodeURIComponent(returnUrl)}`);
     };
+    // WARN, not ERROR: a fleet user opening an owner-only app is the policy
+    // working as designed (an s2s grant denial is ERROR because it usually
+    // means a missing grant during development).
+    const accessDenied = (c, user) => {
+        opts.logger?.warn('user access denied', { email: user.email, policy, path: c.req.path });
+        c.header('cache-control', 'no-store');
+        if (isApi(c)) {
+            return c.json({ error: 'not enabled for this account', code: ACCESS_DENIED_CODE, email: user.email }, 403);
+        }
+        return c.html(accessDeniedPage({ host: c.req.header('host') ?? 'This app', email: user.email, authUrl }), 403);
+    };
     return createMiddleware(async (c, next) => {
+        const admit = (user) => {
+            if (!userAllowed(policy, user))
+                return accessDenied(c, user);
+            c.set('identity', user);
+            c.set('user', user);
+            return next();
+        };
         // Test-mode user bypass (service-caller test bypass is handled by
         // resolveS2sCaller below, so both paths stay testable).
         if (authMode() === 'test' && !c.req.header('x-test-s2s-caller')) {
             const email = c.req.header('x-test-user') ?? process.env.TEST_USER;
             if (!email)
                 return unauthenticated(c);
-            const user = { type: 'user', email };
-            c.set('identity', user);
-            c.set('user', user);
-            return next();
+            const role = parseRole(c.req.header('x-test-user-role') ?? process.env.TEST_USER_ROLE) ?? 'invited';
+            return admit({ type: 'user', email, role });
         }
         // Service-to-service path.
         if (c.req.header('authorization') || c.req.header('x-test-s2s-caller')) {
@@ -72,9 +110,7 @@ export function requireIdentity(opts) {
         if (cached && cached.expires > Date.now()) {
             if (!cached.user)
                 return unauthenticated(c);
-            c.set('identity', cached.user);
-            c.set('user', cached.user);
-            return next();
+            return admit(cached.user);
         }
         let res;
         try {
@@ -86,11 +122,17 @@ export function requireIdentity(opts) {
         }
         if (res.ok) {
             const data = (await res.json());
-            const user = { type: 'user', email: data.email, name: data.name, userId: data.user_id };
+            const role = parseRole(data.role);
+            if (!role) {
+                // An auth service from before roles existed (a rollback), or a
+                // protocol change: a fault, not an "invited" answer. Fail closed,
+                // loudly, and without caching so recovery is instant.
+                opts.logger?.error('whoami answer has no role', { email: data.email, role: data.role });
+                return c.json({ error: 'auth service unavailable' }, 503);
+            }
+            const user = { type: 'user', email: data.email, name: data.name, userId: data.user_id, role };
             cache.set(key, { expires: Date.now() + hitMs, user });
-            c.set('identity', user);
-            c.set('user', user);
-            return next();
+            return admit(user);
         }
         if (res.status === 401) {
             cache.set(key, { expires: Date.now() + missMs });
@@ -100,3 +142,35 @@ export function requireIdentity(opts) {
         return c.json({ error: 'auth service unavailable' }, 503);
     });
 }
+// The fleet-wide "not enabled" page, in the auth service's plain style so
+// every app shows the same thing. Carries nothing but the request's host,
+// the user's address, and the configured auth URL.
+function accessDeniedPage(p) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Not enabled — Plasticine</title>
+<style>
+  :root { --accent: #23a55a; --ink: #1a1a1a; --muted: #6b7280; }
+  body { font-family: system-ui, sans-serif; color: var(--ink); background: #fff;
+         display: flex; min-height: 100vh; margin: 0; align-items: center; justify-content: center; }
+  main { text-align: center; padding: 2rem; max-width: 32rem; }
+  h1 { font-size: 1.4rem; margin-bottom: 0.5rem; }
+  h1 .dot { color: var(--accent); }
+  p.muted { color: var(--muted); font-size: 0.95rem; }
+  a { color: var(--accent); }
+</style>
+</head>
+<body><main>
+<h1>Plasticine<span class="dot">.</span></h1>
+<p><strong>${escapeHtml(p.host)}</strong> is not enabled for your account.</p>
+<p class="muted">You are signed in as ${escapeHtml(p.email)}. To use a different account,
+<a href="${escapeHtml(p.authUrl)}/">sign out</a> first.</p>
+</main></body>
+</html>`;
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch]);
+}

package/dist/db.d.ts

@@ -4,6 +4,10 @@ export interface PoolOptions {
     /** Override the database name (default: env DB_NAME / DATABASE_URL path). */
     database?: string;
     max?: number;
+    /** How long a checkout waits for a free connection before failing (pg's
+     *  default is to wait forever, which turns pool starvation into a silent
+     *  hang instead of an error). */
+    connectionTimeoutMillis?: number;
     /** Receives idle-client errors (see logPoolErrors). Without one they go to
      *  stderr — on the Cloud Logging backstop, but not in Axiom. */
     logger?: Logger;

package/dist/db.js

@@ -49,12 +49,13 @@ async function newPool(opts) {
             user: requireEnv('DB_IAM_USER'),
             database: opts.database ?? requireEnv('DB_NAME'),
             max: opts.max ?? 3, // shared instance: default max_connections is low
+            connectionTimeoutMillis: opts.connectionTimeoutMillis,
         });
     }
     const url = new URL(requireEnv('DATABASE_URL'));
     if (opts.database)
         url.pathname = `/${opts.database}`;
-    return new pg.Pool({ connectionString: url.toString(), max: opts.max ?? 5 });
+    return new pg.Pool({ connectionString: url.toString(), max: opts.max ?? 5, connectionTimeoutMillis: opts.connectionTimeoutMillis });
 }
 /** End a pool and resolve only once every client's connection has actually
  * closed. pg-pool's own `end()` resolves as soon as it has *asked* its idle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "2.5.0",
+  "version": "3.0.1",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",