@pikku/inspector 0.12.18 → 0.12.20

package/CHANGELOG.md

@@ -1,3 +1,103 @@
+## 0.12.20
+
+### Patch Changes
+
+- a027a8e: feat: emit auth provider + plugin metadata as `auth-meta.gen.json` for the console SSO page
+
+  The enabled social providers and Better Auth plugins are now extracted statically
+  and written to a generated `auth-meta.gen.json`, replacing the runtime
+  `setAuthRegistry`/`getAuthRegistry` approach — so the console can show them without
+  evaluating the Better Auth factory.
+  - **inspector**: the `pikkuBetterAuth` inspector now reads the `plugins` array from
+    the `betterAuth({ ... })` config and records each plugin id (the callee name of
+    each `plugins: [organization(), bearer()]` entry) on the auth definition.
+  - **cli**: `pikku auth` (and `pikku all`) emit `auth/pikku-auth-meta.gen.json` (path
+    configurable via `authMetaJsonFile`) containing `basePath`, `hasCredentials`, the
+    enabled `providers` (`id` + `displayName` + `secretId`), and the enabled `plugins`
+    (`id` + `displayName`). The previous `setAuthRegistry(...)` runtime wiring is
+    removed from the generated `auth.gen.ts`.
+  - **better-auth**: exports a `PLUGIN_REGISTRY` and `pluginDisplayName(id)` helper so
+    plugin ids resolve to human-readable names.
+  - **core**: removes the unreleased `setAuthRegistry`/`getAuthRegistry` runtime auth
+    registry (now superseded by `auth-meta.gen.json`).
+  - **addon-console**: `getAuthProviders` reads `auth-meta.gen.json` and returns the
+    configured providers, plugins, and `hasCredentials` flag.
+  - **console**: the Auth Providers (SSO) page fetches `console:getAuthProviders` and
+    marks each provider configured/unconfigured, lists email+password credentials as a
+    provider, and shows the enabled Better Auth plugins.
+
+- a027a8e: fix: address Better Auth review findings (secret/variable batch typing, auth init, guards)
+  - **core**: `SecretService.getSecrets` / `VariablesService.getVariables` (and the
+    Local/Typed/Scoped/AWS implementations) now return `Partial<T>`, honestly
+    reflecting that missing keys are omitted at runtime rather than typing partial
+    data as fully populated. `ScopedSecretService.getSecrets` now throws on a
+    disallowed key instead of silently filtering it out.
+  - **cli**: the generated `services.auth()` thunk clears its memoised promise on
+    rejection, so a transient Better Auth/Kysely startup failure no longer
+    permanently poisons auth for the process lifetime.
+  - **inspector**: the `pikkuBetterAuth` export guard now requires an exported
+    `const` (rejects `export let`/`export var`), matching its error message.
+  - **console**: the Microsoft auth provider's `callbackId` is `microsoft` (the
+    Better Auth provider id) rather than `microsoft-entra-id`.
+
+- a027a8e: feat(auth): migrate auth integration from Auth.js to Better Auth
+
+  The auth integration is now built on [Better Auth](https://better-auth.com)
+  and ships as a single package, `@pikku/better-auth` (replacing the former
+  `@pikku/auth-js`). There is exactly one auth package now.
+  - `pikkuBetterAuth(async ({ secrets, variables }) => betterAuth({ ... }))` is the new
+    single entry point. The CLI inspects the `betterAuth(...)` call and generates:
+    - `auth.gen.ts` — a catch-all `${basePath}{/*splat}` HTTP route per method and
+      a global `betterAuthSession({ auth })` middleware that bridges the Better
+      Auth session into the Pikku wire session.
+    - `auth-secrets.gen.ts` — `wireSecret(BETTER_AUTH_SECRET)` plus a
+      `<PROVIDER>_OAUTH` secret for each configured social provider, and
+      `wireVariable` for non-secret provider config (e.g. `MICROSOFT_TENANT_ID`,
+      `COGNITO_DOMAIN`/`REGION`/`USER_POOL_ID`).
+    - `auth.types.ts` — a typed `pikkuBetterAuth` re-export.
+  - `add-auth` (inspector) walks into the `betterAuth(...)` options to discover the
+    configured providers and required secrets/variables.
+  - The auth secret is now auto-wired by codegen from `BETTER_AUTH_SECRET` — it no
+    longer needs to be registered as a JWT signing key in `services.ts`.
+
+  CLI fix included: scaffold files generated outside `srcDirectories` (e.g. an
+  `auth.gen.ts` under a project's `pikku/` dir) are now added to the inspector's
+  wiring files, so their routes and secret metadata are picked up. The generated
+  wiring imports Pikku types via a resolved relative path instead of a hardcoded
+  `#pikku` specifier, so templates without a `#pikku` import map type-check.
+
+- Updated dependencies [a027a8e]
+- Updated dependencies [a027a8e]
+- Updated dependencies [a027a8e]
+- Updated dependencies [a027a8e]
+  - @pikku/core@0.12.32
+
+## 0.12.19
+
+### Patch Changes
+
+- fe70fe0: fix(db): make classified columns usable in Kysely queries and emit real zod
+
+  Two fixes so data-classified DB columns (`@private`/`@pii`/`@secret`, default
+  `private`) are usable end-to-end instead of poisoning ordinary app code:
+  1. **Brand marker is now optional** (`{ readonly __classification__?: ... }`)
+     in both `@pikku/core` and the `pikku db migrate` schema header. A required
+     marker made a plain value (e.g. `string`) unassignable to a branded column
+     (`Private<string>`), breaking every Kysely `where`/insert/`.set()` operand —
+     any project with classified columns failed to type-check. Optional keeps the
+     brand structurally present (so the inspector's PKU910 output check still
+     detects it) while letting plain values flow IN. The inspector's level read is
+     now union-aware (`'pii' | undefined`) so pii/secret no longer silently
+     downgrade to private.
+  2. **Zod codegen resolves classified `ColumnType<>`** to proper scalars instead
+     of `z.unknown()`. `pikku db migrate` emits `<Table>Z`/`InsertZ`/`PatchZ` from
+     the Select slot, unwrapping the brand and honoring insert-optionality from the
+     Insert slot's `| undefined`. Public `Generated<T>`/bare/nested shapes are
+     unchanged.
+
+- Updated dependencies [fe70fe0]
+  - @pikku/core@0.12.31
+
 ## 0.12.18
 
 ### Patch Changes

package/dist/add/add-auth.d.ts

@@ -1,2 +1,30 @@
 import type { AddWiring } from '../types.js';
+/**
+ * The pikku function id of the single shared auth handler the CLI generates
+ * (`export const authHandler = pikkuSessionlessFunc(...)` in auth.gen.ts). An
+ * exported top-level const collapses the catch-all `/api/auth/**` route onto one
+ * worker, and the export name becomes the function id. Shared with the CLI
+ * codegen and the post-process service stamp so all three agree on the same id
+ * without the inspector having to import `@pikku/better-auth`.
+ */
+export declare const AUTH_HANDLER_FUNC_ID = "authHandler";
+/**
+ * Detects `pikkuBetterAuth((services) => betterAuth({...}))` calls.
+ *
+ * `pikkuBetterAuth` is pure: it wraps a factory that returns a configured better-auth
+ * instance and has NO side effects. The user assigns it to an exported binding,
+ * e.g.
+ *
+ *   export const auth = pikkuBetterAuth(async (services) => betterAuth({ ... }))
+ *
+ * The pikku CLI discovers that single export and generates a catch-all
+ * `auth.gen.ts` that wires `${basePath}/**` to one shared handler, registers the
+ * better-auth session middleware, and emits a `wireSecret` for every configured
+ * social provider — so the auth routes and secret requirements flow through
+ * normal inspection into the deploy manifest.
+ *
+ * This add-wiring records the exported binding name, source file, basePath, the
+ * `socialProviders` keys, whether email/password is enabled, and the services
+ * the factory touches. Exactly one `pikkuBetterAuth` is allowed per codebase.
+ */
 export declare const addAuth: AddWiring;

package/dist/add/add-auth.js

@@ -1,34 +1,188 @@
 import * as ts from 'typescript';
 import { ErrorCode } from '../error-codes.js';
+import { extractServicesFromFunction } from '../utils/extract-services.js';
+/**
+ * The pikku function id of the single shared auth handler the CLI generates
+ * (`export const authHandler = pikkuSessionlessFunc(...)` in auth.gen.ts). An
+ * exported top-level const collapses the catch-all `/api/auth/**` route onto one
+ * worker, and the export name becomes the function id. Shared with the CLI
+ * codegen and the post-process service stamp so all three agree on the same id
+ * without the inspector having to import `@pikku/better-auth`.
+ */
+export const AUTH_HANDLER_FUNC_ID = 'authHandler';
+/** The default better-auth base path when `basePath` is not configured. */
+const DEFAULT_BASE_PATH = '/api/auth';
+/**
+ * Find the first `betterAuth({...})` call anywhere inside the `pikkuBetterAuth`
+ * factory body. Supports both `(s) => betterAuth({...})` and
+ * `(s) => { ...; return betterAuth({...}) }`.
+ */
+const findBetterAuthCall = (node) => {
+    let found;
+    const visit = (n) => {
+        if (found)
+            return;
+        if (ts.isCallExpression(n) &&
+            ts.isIdentifier(n.expression) &&
+            n.expression.text === 'betterAuth') {
+            found = n;
+            return;
+        }
+        ts.forEachChild(n, visit);
+    };
+    visit(node);
+    return found;
+};
+/** Read a string-literal property off an object literal, if present. */
+const readStringProp = (obj, name) => {
+    const prop = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
+        (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+        p.name.text === name);
+    if (prop && ts.isStringLiteral(prop.initializer))
+        return prop.initializer.text;
+    return undefined;
+};
+/** Find an object-literal-valued property off an object literal, if present. */
+const readObjectProp = (obj, name) => {
+    const prop = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
+        (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+        p.name.text === name);
+    if (prop && ts.isObjectLiteralExpression(prop.initializer))
+        return prop.initializer;
+    return undefined;
+};
+/** Find an array-literal-valued property off an object literal, if present. */
+const readArrayProp = (obj, name) => {
+    const prop = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
+        (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
+        p.name.text === name);
+    if (prop && ts.isArrayLiteralExpression(prop.initializer))
+        return prop.initializer;
+    return undefined;
+};
+/**
+ * Read the callee name of a `plugins: [...]` entry. better-auth plugins are
+ * factory calls (`bearer()`, `twoFactor({ ... })`, `admin()`); the entry's id
+ * is the called function's name. Member-expression callees (`foo.bar()`) and
+ * non-call entries are ignored.
+ */
+const readPluginId = (el) => {
+    if (ts.isCallExpression(el) && ts.isIdentifier(el.expression))
+        return el.expression.text;
+    return undefined;
+};
+/**
+ * Detects `pikkuBetterAuth((services) => betterAuth({...}))` calls.
+ *
+ * `pikkuBetterAuth` is pure: it wraps a factory that returns a configured better-auth
+ * instance and has NO side effects. The user assigns it to an exported binding,
+ * e.g.
+ *
+ *   export const auth = pikkuBetterAuth(async (services) => betterAuth({ ... }))
+ *
+ * The pikku CLI discovers that single export and generates a catch-all
+ * `auth.gen.ts` that wires `${basePath}/**` to one shared handler, registers the
+ * better-auth session middleware, and emits a `wireSecret` for every configured
+ * social provider — so the auth routes and secret requirements flow through
+ * normal inspection into the deploy manifest.
+ *
+ * This add-wiring records the exported binding name, source file, basePath, the
+ * `socialProviders` keys, whether email/password is enabled, and the services
+ * the factory touches. Exactly one `pikkuBetterAuth` is allowed per codebase.
+ */
 export const addAuth = (logger, node, _checker, state) => {
     if (!ts.isCallExpression(node))
         return;
     const expression = node.expression;
-    if (!ts.isIdentifier(expression) || expression.text !== 'wireAuth')
+    if (!ts.isIdentifier(expression) || expression.text !== 'pikkuBetterAuth')
         return;
-    const firstArg = node.arguments[0];
-    if (!firstArg || !ts.isObjectLiteralExpression(firstArg))
-        return;
-    const providersProp = firstArg.properties.find((p) => ts.isPropertyAssignment(p) &&
-        (ts.isIdentifier(p.name) || ts.isStringLiteral(p.name)) &&
-        p.name.text === 'providers');
     const sourceFile = node.getSourceFile().fileName;
-    state.auth.files.add(sourceFile);
-    if (!providersProp) {
+    // Walk up to the `export const <name> = pikkuBetterAuth(...)` binding.
+    const varDecl = node.parent;
+    if (!ts.isVariableDeclaration(varDecl) || !ts.isIdentifier(varDecl.name)) {
+        logger.critical(ErrorCode.AUTH_NOT_EXPORTED, `pikkuBetterAuth(...) must be assigned to an exported const, e.g. \`export const auth = pikkuBetterAuth((services) => betterAuth({...}))\` in ${sourceFile}`);
         return;
     }
-    if (!ts.isArrayLiteralExpression(providersProp.initializer)) {
-        logger.critical(ErrorCode.MISSING_NAME, 'wireAuth: providers must be an array literal of string literals.');
+    const exportName = varDecl.name.text;
+    // VariableDeclaration -> VariableDeclarationList -> VariableStatement
+    const declList = varDecl.parent;
+    const varStatement = declList?.parent;
+    const isConst = ts.isVariableDeclarationList(declList) &&
+        (declList.flags & ts.NodeFlags.Const) !== 0;
+    const isExported = varStatement &&
+        ts.isVariableStatement(varStatement) &&
+        varStatement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+    if (!isExported || !isConst) {
+        logger.critical(ErrorCode.AUTH_NOT_EXPORTED, `pikkuBetterAuth(...) must be assigned to an exported const so the CLI can import it. Use \`export const ${exportName} = pikkuBetterAuth(...)\` in ${sourceFile}`);
         return;
     }
-    for (const element of providersProp.initializer
-        .elements) {
-        if (!ts.isStringLiteral(element)) {
-            logger.critical(ErrorCode.NON_LITERAL_WIRE_NAME, `wireAuth: each provider must be a string literal. Found: ${element.getText()}`);
-            return;
+    if (state.auth.definition) {
+        logger.critical(ErrorCode.DUPLICATE_AUTH_DEFINITION, `Only one pikkuBetterAuth(...) is allowed per codebase. Found a second in ${sourceFile} (first: ${state.auth.definition.sourceFile}).`);
+        return;
+    }
+    // The single argument must be the factory: (services) => betterAuth({...}).
+    const factory = node.arguments[0];
+    if (!factory ||
+        (!ts.isArrowFunction(factory) && !ts.isFunctionExpression(factory))) {
+        logger.critical(ErrorCode.MISSING_NAME, `pikkuBetterAuth(...) must take a factory function returning betterAuth(...), e.g. \`pikkuBetterAuth((services) => betterAuth({...}))\` in ${sourceFile}`);
+        return;
+    }
+    state.auth.files.add(sourceFile);
+    // Derive the services the factory touches from its destructured first param —
+    // the same convention as every other pikku wiring. A non-destructured param
+    // yields optimized:false (handler gets all singleton services), with the
+    // standard diagnostic steering the user to destructure.
+    const services = extractServicesFromFunction(factory);
+    // Find the inner betterAuth({...}) call to read providers/basePath/credentials.
+    let basePath = DEFAULT_BASE_PATH;
+    let hasCredentials = false;
+    const betterAuthCall = findBetterAuthCall(factory);
+    const config = betterAuthCall?.arguments[0];
+    if (config && ts.isObjectLiteralExpression(config)) {
+        basePath = readStringProp(config, 'basePath') ?? DEFAULT_BASE_PATH;
+        const emailAndPassword = readObjectProp(config, 'emailAndPassword');
+        if (emailAndPassword) {
+            // `emailAndPassword: { enabled: true }` — treat a present block without an
+            // explicit `enabled: false` as credentials being available.
+            const enabledProp = emailAndPassword.properties.find((p) => ts.isPropertyAssignment(p) &&
+                ts.isIdentifier(p.name) &&
+                p.name.text === 'enabled');
+            hasCredentials =
+                !enabledProp ||
+                    enabledProp.initializer.kind !== ts.SyntaxKind.FalseKeyword;
         }
-        if (!state.auth.providers.includes(element.text)) {
-            state.auth.providers.push(element.text);
+        const socialProviders = readObjectProp(config, 'socialProviders');
+        if (socialProviders) {
+            for (const prop of socialProviders.properties) {
+                const key = (ts.isPropertyAssignment(prop) ||
+                    ts.isShorthandPropertyAssignment(prop)) &&
+                    (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name))
+                    ? prop.name.text
+                    : undefined;
+                if (key && !state.auth.providers.includes(key)) {
+                    state.auth.providers.push(key);
+                }
+            }
         }
+        const plugins = readArrayProp(config, 'plugins');
+        if (plugins) {
+            for (const el of plugins.elements) {
+                const id = readPluginId(el);
+                if (id && !state.auth.plugins.includes(id)) {
+                    state.auth.plugins.push(id);
+                }
+            }
+        }
+    }
+    else {
+        logger.warn(`pikkuBetterAuth in ${sourceFile}: could not statically find a betterAuth({...}) call inside the factory — social provider secrets will not be auto-wired.`);
     }
+    state.auth.definition = {
+        exportName,
+        sourceFile,
+        basePath,
+        hasCredentials,
+        plugins: [...state.auth.plugins],
+        services,
+    };
 };

package/dist/error-codes.d.ts

@@ -30,6 +30,8 @@ export declare enum ErrorCode {
     INLINE_SCHEMA = "PKU489",
     FUNCTION_METADATA_NOT_FOUND = "PKU559",
     HANDLER_NOT_RESOLVED = "PKU568",
+    DUPLICATE_AUTH_DEFINITION = "PKU581",
+    AUTH_NOT_EXPORTED = "PKU582",
     ROUTE_PARAM_MISMATCH = "PKU571",
     ROUTE_QUERY_MISMATCH = "PKU572",
     AUTH_DISABLED_REQUIRES_SESSIONLESS = "PKU573",

package/dist/error-codes.js

@@ -34,6 +34,9 @@ export var ErrorCode;
     // Function errors
     ErrorCode["FUNCTION_METADATA_NOT_FOUND"] = "PKU559";
     ErrorCode["HANDLER_NOT_RESOLVED"] = "PKU568";
+    // Auth errors
+    ErrorCode["DUPLICATE_AUTH_DEFINITION"] = "PKU581";
+    ErrorCode["AUTH_NOT_EXPORTED"] = "PKU582";
     // HTTP Route errors
     ErrorCode["ROUTE_PARAM_MISMATCH"] = "PKU571";
     ErrorCode["ROUTE_QUERY_MISMATCH"] = "PKU572";

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export type { TypesMap } from './types-map.js';
 export type * from './types.js';
 export type { FilesAndMethodsErrors } from './utils/get-files-and-methods.js';
 export { ErrorCode } from './error-codes.js';
+export { AUTH_HANDLER_FUNC_ID } from './add/add-auth.js';
 export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
 export type { SerializableInspectorState } from './utils/serialize-inspector-state.js';
 export { filterInspectorState } from './utils/filter-inspector-state.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export { inspect, getInitialInspectorState } from './inspector.js';
 export { ErrorCode } from './error-codes.js';
+export { AUTH_HANDLER_FUNC_ID } from './add/add-auth.js';
 export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
 export { filterInspectorState } from './utils/filter-inspector-state.js';
 export { resolveDeployTarget } from './utils/resolve-deploy-target.js';

package/dist/inspector.js

@@ -4,7 +4,7 @@ import { visitSetup, visitRoutes } from './visit.js';
 import { TypesMap } from './types-map.js';
 import { getFilesAndMethods } from './utils/get-files-and-methods.js';
 import { findCommonAncestor } from './utils/find-root-dir.js';
-import { aggregateRequiredServices, validateAgentModels, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, computeDiagnostics, validateSchemaWiringSeparation, } from './utils/post-process.js';
+import { aggregateRequiredServices, stampAuthHandlerServices, validateAgentModels, validateSecretOverrides, validateVariableOverrides, validateCredentialOverrides, computeResolvedIOTypes, computeMiddlewareGroupsMeta, computePermissionsGroupsMeta, computeRequiredSchemas, computeDiagnostics, validateSchemaWiringSeparation, } from './utils/post-process.js';
 import { generateOpenAPISpec } from './utils/serialize-openapi-json.js';
 import { pikkuState } from '@pikku/core/internal';
 import { resolveLatestVersions } from './utils/resolve-versions.js';
@@ -117,7 +117,9 @@ export function getInitialInspectorState(rootDir) {
         },
         auth: {
             providers: [],
+            plugins: [],
             files: new Set(),
+            definition: null,
         },
         secrets: {
             definitions: [],
@@ -254,6 +256,9 @@ export const inspect = async (logger, routeFiles, options = {}) => {
     logger.debug(`Get files and methods completed in ${(performance.now() - startFilesAndMethods).toFixed(2)}ms`);
     if (!options.setupOnly) {
         const startAggregate = performance.now();
+        // Apply the inspected auth handler service set before aggregation so it
+        // flows into requiredServices (the generated handler's own func is opaque).
+        stampAuthHandlerServices(state);
         aggregateRequiredServices(state);
         logger.debug(`Aggregate required services completed in ${(performance.now() - startAggregate).toFixed(2)}ms`);
         computeResolvedIOTypes(state);

package/dist/types.d.ts

@@ -246,6 +246,37 @@ export interface InspectorDiagnostic {
     sourceFile: string;
     position: number;
 }
+/** A single discovered `export const X = pikkuBetterAuth((services) => betterAuth({...}))`. */
+export interface AuthDefinition {
+    /** The exported binding name the CLI imports (`export const <exportName>`). */
+    exportName: string;
+    /** Absolute path of the file declaring it. */
+    sourceFile: string;
+    /** better-auth base path (the `basePath` option, default `/api/auth`). */
+    basePath: string;
+    /** Whether email/password auth is enabled (`emailAndPassword.enabled`). Written
+     *  into the generated `auth-meta.gen.json` so the console knows credentials are
+     *  available alongside the OAuth providers. */
+    hasCredentials: boolean;
+    /** better-auth plugin ids used in the config's `plugins: [...]` array, read
+     *  from each entry's callee name (e.g. `bearer()` → `'bearer'`). Written into
+     *  `auth-meta.gen.json` so the console SSO page can show which plugins are
+     *  enabled. */
+    plugins: string[];
+    /**
+     * Singleton services the generated auth handler must have available at
+     * runtime — the services the `pikkuBetterAuth` factory reaches for (either
+     * destructured from its first param, or accessed as `services.<name>` in its
+     * body). better-auth's factory typically touches `secrets` and the DB.
+     *
+     * The generated `authHandler` calls `createAuthHandler(...).func`, an opaque
+     * property access the inspector can't see through; without this stamp the
+     * deployed auth worker would instantiate none of these services and the
+     * factory would receive an undefined `kysely`. Re-derived every inspect and
+     * applied to the handler meta before service aggregation runs.
+     */
+    services: FunctionServicesMeta;
+}
 export interface InspectorState {
     rootDir: string;
     singletonServicesTypeImportMap: PathToNameAndType;
@@ -341,7 +372,12 @@ export interface InspectorState {
     };
     auth: {
         providers: string[];
+        plugins: string[];
         files: Set<string>;
+        /** The single `export const X = pikkuBetterAuth({...})` discovered in the
+         *  codebase, if any. The CLI generates the `/auth/*` HTTP wiring from it.
+         *  More than one `pikkuBetterAuth` is a critical error. */
+        definition: AuthDefinition | null;
     };
     secrets: {
         definitions: SecretDefinitions;

package/dist/utils/check-pii-output.js

@@ -17,8 +17,12 @@ export function findPiiPaths(checker, type, path = '', depth = 0, seen = new Set
         return [];
     seen.add(type);
     // ── Is this type itself branded? ─────────────────────────────────────────
-    // Private<T> = T & { readonly __classification__: 'private' }  →  isIntersection()
-    // where one constituent has a `__classification__` property whose type is a string literal.
+    // Private<T> = T & { readonly __classification__?: 'private' }  →  isIntersection()
+    // where one constituent has a `__classification__` property whose type is a
+    // string literal. The marker is OPTIONAL (so plain values stay assignable to
+    // branded columns), which means its resolved type is `'private' | undefined` —
+    // a union, not a bare literal. Read the level union-aware via `literalString`,
+    // otherwise pii/secret silently downgrade to the `'private'` fallback.
     if (type.isIntersection()) {
         for (const t of type.types) {
             const classificationProp = t
@@ -28,7 +32,7 @@ export function findPiiPaths(checker, type, path = '', depth = 0, seen = new Set
                 const decl = classificationProp.valueDeclaration ??
                     classificationProp.declarations?.[0];
                 const classification = decl
-                    ? (checker.getTypeOfSymbolAtLocation(classificationProp, decl)?.value ?? 'private')
+                    ? (literalString(checker.getTypeOfSymbolAtLocation(classificationProp, decl)) ?? 'private')
                     : 'private';
                 return [{ path: path || '<return value>', classification }];
             }
@@ -71,3 +75,22 @@ export function findPiiPaths(checker, type, path = '', depth = 0, seen = new Set
     }
     return violations;
 }
+/**
+ * Recover a string-literal value from a type that may be the literal itself or a
+ * union containing it (e.g. `'private' | undefined`, produced by the optional
+ * `__classification__?` marker). Returns undefined when no string literal is
+ * present so the caller can apply its own fallback.
+ */
+function literalString(type) {
+    const value = type.value;
+    if (typeof value === 'string')
+        return value;
+    if (type.isUnion()) {
+        for (const member of type.types) {
+            const found = literalString(member);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return undefined;
+}

package/dist/utils/post-process.d.ts

@@ -1,5 +1,19 @@
 import type { InspectorState, InspectorLogger, InspectorOptions } from '../types.js';
 import type { MiddlewareMetadata, PermissionMetadata } from '@pikku/core';
+/**
+ * Stamp the inspected authorize/callbacks service set onto the generated auth
+ * handler's function meta.
+ *
+ * The CLI generates `export const authHandler = pikkuSessionlessFunc({ func:
+ * createAuthHandler(...).func })`. That `func` is an opaque property access, so
+ * normal extraction records zero services for the handler — which would leave
+ * the deployed auth worker without `kysely`/`variables`/`secrets` and break
+ * `authorize` at runtime. `add-auth` already computed the real dependency set
+ * (from the pikkuBetterAuth source) into `state.auth.definition.services`; copy it
+ * onto the handler meta. Re-derived every inspect and ordered BEFORE
+ * `aggregateRequiredServices` so it flows into `requiredServices`.
+ */
+export declare function stampAuthHandlerServices(state: InspectorState | Omit<InspectorState, 'typesLookup'>): void;
 /**
  * Helper to extract wire-level middleware/permission names from metadata.
  * Only extracts type:'wire' variants (individual middleware/permissions).

package/dist/utils/post-process.js

@@ -1,5 +1,31 @@
 import { extractTypeKeys } from './type-utils.js';
 import { ErrorCode } from '../error-codes.js';
+import { AUTH_HANDLER_FUNC_ID } from '../add/add-auth.js';
+/**
+ * Stamp the inspected authorize/callbacks service set onto the generated auth
+ * handler's function meta.
+ *
+ * The CLI generates `export const authHandler = pikkuSessionlessFunc({ func:
+ * createAuthHandler(...).func })`. That `func` is an opaque property access, so
+ * normal extraction records zero services for the handler — which would leave
+ * the deployed auth worker without `kysely`/`variables`/`secrets` and break
+ * `authorize` at runtime. `add-auth` already computed the real dependency set
+ * (from the pikkuBetterAuth source) into `state.auth.definition.services`; copy it
+ * onto the handler meta. Re-derived every inspect and ordered BEFORE
+ * `aggregateRequiredServices` so it flows into `requiredServices`.
+ */
+export function stampAuthHandlerServices(state) {
+    const definition = state.auth.definition;
+    if (!definition)
+        return;
+    const handlerMeta = state.functions.meta[AUTH_HANDLER_FUNC_ID];
+    if (!handlerMeta)
+        return;
+    handlerMeta.services = {
+        optimized: definition.services.optimized,
+        services: [...definition.services.services],
+    };
+}
 /**
  * Helper to extract wire-level middleware/permission names from metadata.
  * Only extracts type:'wire' variants (individual middleware/permissions).

package/dist/utils/serialize-inspector-state.d.ts

@@ -205,7 +205,9 @@ export interface SerializableInspectorState {
     };
     auth: {
         providers: string[];
+        plugins: string[];
         files: string[];
+        definition: InspectorState['auth']['definition'];
     };
     secrets: {
         definitions: InspectorState['secrets']['definitions'];

package/dist/utils/serialize-inspector-state.js

@@ -100,7 +100,9 @@ export function serializeInspectorState(state) {
         },
         auth: {
             providers: state.auth.providers,
+            plugins: state.auth.plugins,
             files: Array.from(state.auth.files),
+            definition: state.auth.definition,
         },
         secrets: {
             definitions: state.secrets.definitions,
@@ -252,7 +254,9 @@ export function deserializeInspectorState(data) {
         },
         auth: {
             providers: data.auth?.providers || [],
+            plugins: data.auth?.plugins || [],
             files: new Set(data.auth?.files || []),
+            definition: data.auth?.definition || null,
         },
         secrets: {
             definitions: data.secrets?.definitions || [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.12.18",
+  "version": "0.12.20",
   "author": "yasser.fadl@gmail.com",
   "license": "BUSL-1.1",
   "type": "module",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@openapi-contrib/json-schema-to-openapi-schema": "^4.3.1",
-    "@pikku/core": "^0.12.30",
+    "@pikku/core": "^0.12.32",
     "path-to-regexp": "^8.3.0",
     "ts-json-schema-generator": "^2.5.0",
     "tsx": "^4.21.0",