@pikku/core 0.12.113 → 0.12.114

package/CHANGELOG.md

@@ -1,3 +1,66 @@
+## 0.12.114
+
+### Patch Changes
+
+- cb8f57e: Global middleware now runs for a dispatch that belongs to an addon, not just for one in the root namespace.
+
+  `combineMiddleware` read the global list out of a single namespace — the `packageName` the dispatch carried. For anything wired by the application itself that namespace is `null`, so it worked; for a wiring contributed by an addon (an MCP tool registered through `wireAddon({ mcp: [...] })`, say) it was the addon's own package name, and the application's globals were simply not in that list. The practical effect was that an addon's tools ran with no session middleware at all: every one of them refused with "authentication required" no matter who was calling, while the identical function reached through HTTP authenticated fine.
+
+  Global middleware is application-wide by definition, and an addon's function is still running inside the host application, so the root namespace always applies. A dispatch in the root namespace resolves `[null]` as before; one in an addon resolves `[null, packageName]` — the host's globals first, then the addon's own. Globals registered by one addon still do not reach another's dispatches.
+
+- cb8f57e: MCP clients can now discover that a server needs signing in to, and can see tools whose names carry a namespace.
+
+  Three separate reasons a client ended up connected to a server it could do nothing with:
+
+  - **The handshake was never challenged.** A client decides at connection time whether a server speaks OAuth, and all it has to go on is whether `initialize` came back `401` with a `WWW-Authenticate` challenge. Answering it `200` and then refusing every subsequent call told the client "no sign-in needed" and then gave it nothing — Claude's connector setup, for one, reported the server as open access. `initialize` is now challenged when `mcpEveryTargetRequiresSession()` holds, which is the only case where answering it openly is a lie; a server with even one open target still completes the handshake unauthenticated, as it should.
+  - **Namespaced names were dropped on the floor.** MCP constrains tool and prompt names to `[A-Za-z0-9_-]{1,64}`, and pikku's namespace separator is `:`. Clients discard the names they cannot accept rather than failing the connection, so an addon's entire surface went missing with nothing more than a note about "tools with unsupported names". Names are now rewritten at the transport boundary (`mcpWireName`) and resolved back on the way in (`mcpResolveWireName`), so `bb2:getMe` is offered as `bb2_getMe` and calls to it dispatch correctly. The registry keeps its own spelling, since that is what dispatch keys on, and a tool genuinely registered under the wire spelling still wins over a rewritten match.
+  - **An addon-only app generated no tool metadata.** `pikku all` decided whether to emit the MCP file from the set of source files calling `wireMCPTool`/`Resource`/`Prompt`. An addon that contributes its tools through `wireAddon({ mcp: [...] })` adds none, so an application whose only MCP surface came from addons got neither wirings nor meta — the tools were listed from `mcp.gen.json` and then every call failed to resolve, because `toolsMeta` (which carries the `pikkuFuncId`) had never been written. Content now decides; the file set only decides whether there are imports to serialize.
+
+  Also in here: the resource URL advertised in the challenge honours `X-Forwarded-Proto` and `X-Forwarded-Host`, so a server behind a TLS-terminating proxy advertises the `https://` URL the client actually reached rather than its own internal `http://` origin — which the client would reject as a resource mismatch.
+
+- 6db6a14: A wiring can now decide whether an addon's credential is per-user or deployment-wide
+
+  `wireAddon`'s `credentialOverrides` takes an object as well as a rename string:
+
+  ```ts
+  wireAddon({
+    name: 'gmail',
+    package: '@pikku/addon-gmail',
+    credentialOverrides: {
+      gmailOAuth: { mode: 'wire' }, // each user connects their own
+      calendarOAuth: { name: 'CAL', mode: 'singleton' },
+    },
+  })
+  ```
+
+  An addon author declares a default with `defineCredential`; the deployment decides, so one addon serves both a per-user product and a single team account.
+
+  The wire credential service now resolves each credential by what it _is_ rather than by what a lookup returned: `wire` reads only the user's value, `singleton` reads the deployment's. A per-user credential can no longer pick up a platform-level value because the user has not connected — which, before, would have quietly run someone's request against the deployment's own account.
+
+  A credential is never read from the secret vault. The wire credential service no longer takes a `SecretService` at all, so the only way a credential arrives is the one its mode names — the user's own value, or the deployment's.
+
+  Modes are resolved at generation time into the credentials meta, so the console's connect flow reflects the wiring rather than the addon's default.
+
+  Two credentials that resolve to one name are rejected unless they agree on the mode. Generation writes a single metadata entry per name, so a `wire` credential aliased onto a `singleton` one used to take whichever wiring was read last — a per-user credential served from the deployment's own account, or a deployment credential handed out per user. The inspector reports the collision against both wirings by name, and `buildCredentialResolutions` refuses it at runtime too.
+
+  A mode-only override is checked against the credential it names. `{ mode: 'wire' }` renames nothing, so nothing was validated: an override naming a credential that does not exist was dropped in silence and the credential kept the mode its author declared.
+
+  A credential the wiring resolves as `singleton` is no longer read out of the user's own store. Per-user values are imported first and a name already present is left alone, so a value stored under a singleton's name — from an earlier wiring, or a connect flow since rewired — decided what the deployment's own slot resolved to. It is now skipped by mode, the same way a `wire` credential is kept away from the deployment's value.
+
+  The project's own credentials are registered into pikku state from the generated credentials file, so `wire.getCredential` resolves an app-level singleton the same way it resolves an addon's.
+
+  `pikku new addon` no longer requires a `pikku.config.json` in the working directory. Scaffolding an addon is something you do before a project config exists, so the command now reads one when it is there and falls back to the working directory when it is not.
+
+  An addon's `pikkuAddonWireServices` factory now declares the same service contract its singleton factory does: what it destructures off the parent's bag is required, and what it returns is built by the addon. Before, a service an addon built per wire was demanded from the consumer, and a wire-only addon declared no contract at all. A nested callback that names its own parameter after the factory's is no longer read as the factory's own: what it destructured went onto the addon's contract, so a consumer was asked for a service the addon never wanted from them.
+
+  An OAuth2 credential now implies its app secret, so nobody hand-writes one. The client id and secret an OAuth app needs is the same shape every time — `OAuth2AppCredential`, which is what the runtime already reads it as — so the inspector registers a secret for each credential's `appCredentialSecretId`. A hand-written `defineSecret` covering that id still wins, so an author who wants their own description or `docsUrl` keeps it. The derived secret is optional, matching what every hand-written declaration chose: an addon that also authenticates by API key must still deploy without an OAuth app configured.
+
+  `optional` now means a secret is not reported as missing. `getMissing()` filtered on "not configured" alone, so a secret whose declaration said absence was supported still showed up on the list of things a deployment had to go and supply — burying the ones that genuinely were. `getAllStatus()` still reports it, flagged `optional`.
+
+  An OAuth2 secret carries its declaration's `optional` through code generation, to the app credential and to the token store alike: nobody connects without the client id and secret, so a deployment allowed to omit the app is never asked for its tokens either. That branch never looked at the flag before.
+
+  `credentialOAuthProviders` treats an app secret that resolves `undefined` as unconfigured. An optional secret resolves rather than throws, so the absence arrived past the `catch` that was meant to skip the provider — and `.reveal()` on it threw a `TypeError` that took every `getSession` down with it, which is the exact failure that code exists to prevent.
+
 ## 0.12.113
 
 ### Patch Changes

package/dist/function/function-runner.js

@@ -11,6 +11,7 @@ import { MissingSessionError, ReadonlySessionError } from '../errors/errors.js';
 import { verifyScopes } from '../scopes.js';
 import { assertFeatureAvailable } from '../wirings/flag/assert-feature-available.js';
 import { PikkuCredentialWireService, createWireServicesCredentialWireProps, } from '../services/credential-wire-service.js';
+import { buildCredentialResolutions, credentialOverrideAliases, } from '../wirings/credential/credential-overrides.js';
 import { defaultPikkuUserIdResolver } from '../services/pikku-user-id.js';
 import { createInvocationAudit, resolveAuditConfig, } from '../services/audit-service.js';
 import { createInvocationAnalytics } from '../analytics/analytics.js';
@@ -125,6 +126,7 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
     const resolvedWire = allChannelMiddleware.length > 0 && wire.channel
         ? wrapChannelWithMiddleware(wire, resolvedSingletonServices, allChannelMiddleware)
         : wire;
+    const declaredCredentials = pikkuState(funcPackageName ?? null, 'package', 'credentialsMeta');
     // Set up early so middleware can use setCredential. An addon instance with
     // credentialOverrides always gets a fresh alias-aware service, even when a
     // parent credential service is already present on the wire.
@@ -132,12 +134,16 @@ export const runPikkuFunc = async (wireType, wireId, funcName, { singletonServic
         // Credentials belong to the consuming project, so resolve them via the
         // project's credentialService (the addon's own singletons may not carry it).
         const aliasedCredentialWireService = new PikkuCredentialWireService(singletonServices.credentialService ??
-            resolvedSingletonServices.credentialService, resolvedWire, addonInstance.credentialOverrides);
+            resolvedSingletonServices.credentialService, resolvedWire, credentialOverrideAliases(addonInstance.credentialOverrides), {
+            resolutions: buildCredentialResolutions(declaredCredentials, addonInstance.credentialOverrides),
+        });
         Object.assign(resolvedWire, createWireServicesCredentialWireProps(aliasedCredentialWireService));
     }
     else if (!resolvedWire.getCredentials) {
         const resolvedCredentialWireService = credentialWireService ??
-            new PikkuCredentialWireService(resolvedSingletonServices.credentialService, resolvedWire);
+            new PikkuCredentialWireService(resolvedSingletonServices.credentialService, resolvedWire, undefined, {
+                resolutions: buildCredentialResolutions(declaredCredentials, undefined),
+            });
         Object.assign(resolvedWire, createWireServicesCredentialWireProps(resolvedCredentialWireService));
     }
     const resolvedAuditConfig = resolveAuditConfig(funcConfig.audit);

package/dist/middleware-runner.js

@@ -88,9 +88,14 @@ export const combineMiddleware = (wireType, uid, { wireInheritedMiddleware, wire
         return middlewareCache[wireType][uid];
     }
     const resolved = [];
-    const globals = pikkuState(packageName, 'middleware', 'global');
-    if (globals && globals.length > 0) {
-        resolved.push(...globals);
+    // Global middleware is application-wide, so the root namespace always
+    // applies — an addon's function still runs inside the host application.
+    // See `global-middleware-resolves-from-the-root-namespace-too.md`.
+    for (const ns of packageName === null ? [null] : [null, packageName]) {
+        const globals = pikkuState(ns, 'middleware', 'global');
+        if (globals && globals.length > 0) {
+            resolved.push(...globals);
+        }
     }
     if (wireInheritedMiddleware) {
         for (const meta of wireInheritedMiddleware) {

package/dist/services/credential-wire-service.d.ts

@@ -1,13 +1,29 @@
 import type { CredentialService } from './credential-service.js';
 import type { PikkuRawWire } from '../types/core.types.js';
+/**
+ * Where one credential's value is read from. Decided by what the credential IS
+ * — its declared type, as the wiring may have overridden it — and never by
+ * whether a per-user lookup came back empty. An absence-driven fallback would
+ * let a user who has not connected read the deployment's own token.
+ */
+export type CredentialResolution = {
+    mode: 'wire';
+} | {
+    mode: 'singleton';
+};
+export type CredentialResolutionConfig = {
+    /** Keyed by the resolved (post-alias) credential name. */
+    resolutions: Record<string, CredentialResolution>;
+};
 export declare class PikkuCredentialWireService {
     private credentialService?;
     private wire?;
     private aliases?;
+    private resolution?;
     private credentials;
     private loaded;
     private loadPromise;
-    constructor(credentialService?: CredentialService | undefined, wire?: PikkuRawWire | undefined, aliases?: Record<string, string> | undefined);
+    constructor(credentialService?: CredentialService | undefined, wire?: PikkuRawWire | undefined, aliases?: Record<string, string> | undefined, resolution?: CredentialResolutionConfig | undefined);
     private resolveName;
     /**
      * A credential is one of the few places vault material is meant to end up, so
@@ -35,6 +51,20 @@ export declare class PikkuCredentialWireService {
      * nothing to fetch — so they should reach the fast path too.
      */
     private doLoad;
+    /**
+     * The other half of resolving by type. A user's own store can hold a value
+     * under a name the wiring made `singleton` — from an earlier wiring, or a
+     * connect flow that has since been rewired — and importing it would put the
+     * user in charge of a slot the deployment owns. What `set` wrote is left
+     * alone: that is the deployment's own path, not the user's.
+     */
+    private isSingleton;
+    /**
+     * The `singleton` half of the dispatch. `wire` is absent here on purpose:
+     * those values arrive with `getAll(userId)` above, so a wire credential can
+     * never pick up a platform value that happens to exist.
+     */
+    private loadDeploymentCredentials;
 }
 export declare function createMiddlewareCredentialWireProps(credentialWire: PikkuCredentialWireService): {
     setCredential: (name: string, value: unknown) => void;

package/dist/services/credential-wire-service.js

@@ -4,13 +4,15 @@ export class PikkuCredentialWireService {
     credentialService;
     wire;
     aliases;
+    resolution;
     credentials = {};
     loaded = false;
     loadPromise;
-    constructor(credentialService, wire, aliases) {
+    constructor(credentialService, wire, aliases, resolution) {
         this.credentialService = credentialService;
         this.wire = wire;
         this.aliases = aliases;
+        this.resolution = resolution;
     }
     resolveName(name) {
         return this.aliases?.[name] ?? name;
@@ -73,23 +75,58 @@ export class PikkuCredentialWireService {
      */
     async doLoad() {
         try {
-            if (!this.credentialService || !this.wire)
+            if (!this.credentialService && !this.resolution)
                 return;
-            const userId = defaultPikkuUserIdResolver(this.wire);
-            if (!userId)
-                return;
-            this.wire.pikkuUserId = userId;
-            const allCreds = await this.credentialService.getAll(userId);
-            for (const [name, value] of Object.entries(allCreds)) {
-                if (!(name in this.credentials)) {
-                    this.credentials[name] = value;
+            const userId = this.wire
+                ? defaultPikkuUserIdResolver(this.wire)
+                : undefined;
+            if (this.credentialService && this.wire && userId) {
+                this.wire.pikkuUserId = userId;
+                const allCreds = await this.credentialService.getAll(userId);
+                for (const [name, value] of Object.entries(allCreds)) {
+                    if (this.isSingleton(name))
+                        continue;
+                    if (!(name in this.credentials)) {
+                        this.credentials[name] = value;
+                    }
                 }
             }
+            await this.loadDeploymentCredentials();
         }
         finally {
             this.loaded = true;
         }
     }
+    /**
+     * The other half of resolving by type. A user's own store can hold a value
+     * under a name the wiring made `singleton` — from an earlier wiring, or a
+     * connect flow that has since been rewired — and importing it would put the
+     * user in charge of a slot the deployment owns. What `set` wrote is left
+     * alone: that is the deployment's own path, not the user's.
+     */
+    isSingleton(name) {
+        return this.resolution?.resolutions[name]?.mode === 'singleton';
+    }
+    /**
+     * The `singleton` half of the dispatch. `wire` is absent here on purpose:
+     * those values arrive with `getAll(userId)` above, so a wire credential can
+     * never pick up a platform value that happens to exist.
+     */
+    async loadDeploymentCredentials() {
+        const resolutions = this.resolution?.resolutions;
+        if (!resolutions)
+            return;
+        if (!this.credentialService)
+            return;
+        for (const [name, resolution] of Object.entries(resolutions)) {
+            if (resolution.mode === 'wire' || name in this.credentials)
+                continue;
+            const value = await this.credentialService.get(name);
+            if (value !== null) {
+                this.credentials[name] = value;
+            }
+        }
+    }
 }
 export function createMiddlewareCredentialWireProps(credentialWire) {
     return {

package/dist/services/typed-secret-service.d.ts

@@ -13,6 +13,8 @@ export interface CredentialStatus {
     name: string;
     displayName: string;
     isConfigured: boolean;
+    /** Declared `optional: true`, so absence is a supported state rather than a misconfiguration. */
+    optional?: boolean;
     oauth2?: {
         tokenSecretId: string;
     };
@@ -42,5 +44,14 @@ export declare class TypedSecretService<TMap = Record<string, unknown>> implemen
     deleteSecret(key: string): Promise<void>;
     getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>>;
     getAllStatus(): Promise<CredentialStatus[]>;
+    /**
+     * The secrets a deployment still has to supply.
+     *
+     * An optional one is absent from this list however it is stored: `optional`
+     * already declares that absence is supported, which is why `getSecret`
+     * resolves `undefined` for it rather than throwing. Reporting it as missing
+     * contradicts that, and buries the required secrets someone actually has to
+     * go and configure. `getAllStatus` still reports it, flagged.
+     */
     getMissing(): Promise<CredentialStatus[]>;
 }

package/dist/services/typed-secret-service.js

@@ -65,13 +65,23 @@ export class TypedSecretService {
                 name: meta.name,
                 displayName: meta.displayName,
                 isConfigured: await this.secrets.hasSecret(secretId),
+                optional: meta.optional,
                 oauth2: meta.oauth2,
             });
         }
         return results;
     }
+    /**
+     * The secrets a deployment still has to supply.
+     *
+     * An optional one is absent from this list however it is stored: `optional`
+     * already declares that absence is supported, which is why `getSecret`
+     * resolves `undefined` for it rather than throwing. Reporting it as missing
+     * contradicts that, and buries the required secrets someone actually has to
+     * go and configure. `getAllStatus` still reports it, flagged.
+     */
     async getMissing() {
         const all = await this.getAllStatus();
-        return all.filter((c) => !c.isConfigured);
+        return all.filter((c) => !c.isConfigured && !c.optional);
     }
 }

package/dist/types/state.types.d.ts

@@ -1,3 +1,4 @@
+import type { CredentialOverrides } from '../wirings/credential/credential-overrides.js';
 import type { PikkuErrorConstructor, ErrorDetails } from '../errors/error-handler.js';
 import type { CorePikkuFunctionConfig, CorePermissionGroup, CorePikkuPermission } from '../function/functions.types.js';
 import type { CorePikkuTriggerFunctionConfig } from '../wirings/trigger/trigger.types.js';
@@ -43,7 +44,7 @@ export interface PikkuPackageState {
             /** Per-instance name-aliases: logical name the addon reads -> actual project variable name */
             variableOverrides?: Record<string, string>;
             /** Per-instance name-aliases: logical name the addon reads -> actual project credential name */
-            credentialOverrides?: Record<string, string>;
+            credentialOverrides?: CredentialOverrides;
             /** Secrets the host lends this instance, named as the addon reads them */
             secretGrants?: string[];
             /** Credentials the host lends this instance, named as the addon reads them */

package/dist/wirings/addon/addon-runner.d.ts

@@ -1,9 +1,10 @@
 import type { CoreSingletonServices } from '../../types/core.types.js';
+import type { CredentialOverrides } from '../credential/credential-overrides.js';
 export type AddonInstance = {
     namespace: string;
     secretOverrides?: Record<string, string>;
     variableOverrides?: Record<string, string>;
-    credentialOverrides?: Record<string, string>;
+    credentialOverrides?: CredentialOverrides;
     /** Set by the consuming app: secrets it lends this instance, as the addon names them. */
     secretGrants?: string[];
     /** Set by the consuming app: credentials it lends this instance, as the addon names them. */

package/dist/wirings/addon/wire-addon.d.ts

@@ -1,3 +1,4 @@
+import type { CredentialOverrides } from '../credential/credential-overrides.js';
 import type { CorePikkuMiddleware } from '../../middleware/middleware.types.js';
 export type WireAddonConfig = {
     /** How this instance is addressed. One package may be wired more than once, and the name is what tells the instances apart. */
@@ -23,8 +24,12 @@ export type WireAddonConfig = {
     secretOverrides?: Record<string, string>;
     /** Points a variable the addon reads at a different key in this deployment. */
     variableOverrides?: Record<string, string>;
-    /** Points a credential the addon reads at a different key in this deployment. */
-    credentialOverrides?: Record<string, string>;
+    /**
+     * Points a credential the addon reads at a different key in this deployment,
+     * and — in the object form — decides whether it is per-user or
+     * deployment-wide. An addon declares a default; the wiring decides.
+     */
+    credentialOverrides?: CredentialOverrides;
     /** Extra secrets this instance may read, named as the addon reads them — the scope check runs before `secretOverrides` renames them. */
     secretGrants?: string[];
     /** Credentials this instance may read on top of the ones it declared. */

package/dist/wirings/credential/credential-overrides.d.ts

@@ -0,0 +1,26 @@
+import type { CredentialResolution } from '../../services/credential-wire-service.js';
+/**
+ * How one credential is wired into a deployment. A bare string renames it, as
+ * it always has. The object form also decides where its value is read from,
+ * which is what lets one addon serve a per-user product and a single team
+ * account without the addon author choosing for both.
+ */
+export type CredentialOverride = string | {
+    /** The key this deployment holds the value under. */
+    name?: string;
+    /** `wire` is per user, `singleton` is one value for the deployment. */
+    mode?: 'singleton' | 'wire';
+};
+export type CredentialOverrides = Record<string, CredentialOverride>;
+/** The rename half, in the `Record<string, string>` shape the alias path wants. */
+export declare const credentialOverrideAliases: (overrides: CredentialOverrides | undefined) => Record<string, string>;
+/**
+ * Where each credential the package declared is read from, keyed by the
+ * resolved name so the wire service can look it up without re-aliasing.
+ *
+ * A credential with no override keeps the type its author declared, which is
+ * what makes an addon that reads one way work under either wiring.
+ */
+export declare const buildCredentialResolutions: (declared: Record<string, {
+    type?: string;
+}> | null | undefined, overrides: CredentialOverrides | undefined) => Record<string, CredentialResolution>;

package/dist/wirings/credential/credential-overrides.js

@@ -0,0 +1,45 @@
+/** The rename half, in the `Record<string, string>` shape the alias path wants. */
+export const credentialOverrideAliases = (overrides) => {
+    const aliases = {};
+    for (const [name, override] of Object.entries(overrides ?? {})) {
+        const target = typeof override === 'string' ? override : override.name;
+        if (target) {
+            aliases[name] = target;
+        }
+    }
+    return aliases;
+};
+/**
+ * Where each credential the package declared is read from, keyed by the
+ * resolved name so the wire service can look it up without re-aliasing.
+ *
+ * A credential with no override keeps the type its author declared, which is
+ * what makes an addon that reads one way work under either wiring.
+ */
+export const buildCredentialResolutions = (declared, overrides) => {
+    const resolutions = {};
+    const names = new Set([
+        ...Object.keys(declared ?? {}),
+        ...Object.keys(overrides ?? {}),
+    ]);
+    /** Which declaration put each resolution there, for the collision message. */
+    const claimedBy = {};
+    for (const name of names) {
+        const override = overrides?.[name];
+        const resolved = (typeof override === 'string' ? override : override?.name) ?? name;
+        const mode = (typeof override === 'object' ? override.mode : undefined) ??
+            declared?.[name]?.type;
+        const resolution = mode === 'singleton' ? { mode: 'singleton' } : { mode: 'wire' };
+        const existing = resolutions[resolved];
+        if (existing && existing.mode !== resolution.mode) {
+            throw new Error(`Credentials '${claimedBy[resolved]}' and '${name}' both resolve to '${resolved}' ` +
+                `but disagree on how it is read: '${existing.mode}' and '${resolution.mode}'. ` +
+                `Only one mode can win, so the loser would silently read the other's ` +
+                `value — a per-user credential served from the deployment's own account, ` +
+                `or the reverse. Give them separate names, or wire both to the same mode.`);
+        }
+        resolutions[resolved] = resolution;
+        claimedBy[resolved] = name;
+    }
+    return resolutions;
+};

package/dist/wirings/credential/index.d.ts

@@ -1,3 +1,5 @@
 export { defineCredential } from './define-credential.js';
 export { validateAndBuildCredentialDefinitionsMeta } from './validate-credential-definitions.js';
 export type { CoreCredential, CredentialDefinitionsMeta, CredentialDefinitions, } from './credential.types.js';
+export { credentialOverrideAliases, buildCredentialResolutions, } from './credential-overrides.js';
+export type { CredentialOverride, CredentialOverrides, } from './credential-overrides.js';

package/dist/wirings/credential/index.js

@@ -1,2 +1,3 @@
 export { defineCredential } from './define-credential.js';
 export { validateAndBuildCredentialDefinitionsMeta } from './validate-credential-definitions.js';
+export { credentialOverrideAliases, buildCredentialResolutions, } from './credential-overrides.js';

package/dist/wirings/mcp/index.d.ts

@@ -1,4 +1,5 @@
 export { MCPEndpointRegistry } from './mcp-endpoint-registry.js';
 export { MCPError, wireMCPResource, wireMCPPrompt, runMCPResource, runMCPTool, runMCPPrompt, } from './mcp-runner.js';
-export { getMCPResourcesMeta, getMCPToolsMeta, getMCPPromptsMeta, mcpTargetRequiresSession, } from './mcp-runner.js';
+export { getMCPResourcesMeta, getMCPToolsMeta, getMCPPromptsMeta, mcpTargetRequiresSession, mcpEveryTargetRequiresSession, mcpWireName, mcpResolveWireName, } from './mcp-runner.js';
+export type { McpTargetType } from './mcp-runner.js';
 export type { AssertMCPResourceURIParams, CoreMCPPrompt, CoreMCPResource, MCPPromptResponse, MCPResourceMeta, MCPResourceResponse, MCPToolMeta, MCPToolResponse, MCPPromptMeta, PikkuMCP, } from './mcp.types.js';

package/dist/wirings/mcp/index.js

@@ -1,3 +1,3 @@
 export { MCPEndpointRegistry } from './mcp-endpoint-registry.js';
 export { MCPError, wireMCPResource, wireMCPPrompt, runMCPResource, runMCPTool, runMCPPrompt, } from './mcp-runner.js';
-export { getMCPResourcesMeta, getMCPToolsMeta, getMCPPromptsMeta, mcpTargetRequiresSession, } from './mcp-runner.js';
+export { getMCPResourcesMeta, getMCPToolsMeta, getMCPPromptsMeta, mcpTargetRequiresSession, mcpEveryTargetRequiresSession, mcpWireName, mcpResolveWireName, } from './mcp-runner.js';

package/dist/wirings/mcp/mcp-runner.d.ts

@@ -47,3 +47,15 @@ export declare const getMCPPromptsMeta: () => import("./mcp.types.js").MCPPrompt
  * to authenticate its way towards a tool that does not exist.
  */
 export declare const mcpTargetRequiresSession: (type: 'tool' | 'resource' | 'prompt', name: string) => boolean;
+/**
+ * Whether every registered MCP target needs a session. An empty registry is
+ * not "all gated" — there is nothing to gate.
+ *
+ * See `the-mcp-handshake-is-challenged-only-when-every-target-is-gated.md`.
+ */
+export declare const mcpEveryTargetRequiresSession: () => boolean;
+export type McpTargetType = 'tool' | 'resource' | 'prompt';
+/** How a registered target's name is spelled on the wire. */
+export declare const mcpWireName: (type: McpTargetType, name: string) => string;
+/** The registered name a client's wire name refers to. */
+export declare const mcpResolveWireName: (type: McpTargetType, wireName: string) => string;

package/dist/wirings/mcp/mcp-runner.js

@@ -202,6 +202,9 @@ export const getMCPPromptsMeta = () => {
  * to authenticate its way towards a tool that does not exist.
  */
 export const mcpTargetRequiresSession = (type, name) => {
+    // The transport passes the name exactly as the client sent it, which is the
+    // wire spelling — see `mcpWireName`.
+    name = mcpResolveWireName(type, name);
     const meta = type === 'tool'
         ? pikkuState(null, 'mcp', 'toolsMeta')[name]
         : type === 'resource'
@@ -225,3 +228,73 @@ export const mcpTargetRequiresSession = (type, name) => {
     }
     return !funcMeta.sessionless || funcMeta.auth === true;
 };
+/**
+ * Whether every registered MCP target needs a session. An empty registry is
+ * not "all gated" — there is nothing to gate.
+ *
+ * See `the-mcp-handshake-is-challenged-only-when-every-target-is-gated.md`.
+ */
+export const mcpEveryTargetRequiresSession = () => {
+    const targets = [
+        ['tool', Object.keys(pikkuState(null, 'mcp', 'toolsMeta'))],
+        ['resource', Object.keys(pikkuState(null, 'mcp', 'resourcesMeta'))],
+        ['prompt', Object.keys(pikkuState(null, 'mcp', 'promptsMeta'))],
+    ];
+    let seen = 0;
+    for (const [type, names] of targets) {
+        for (const name of names) {
+            seen++;
+            if (!mcpTargetRequiresSession(type, name)) {
+                return false;
+            }
+        }
+    }
+    return seen > 0;
+};
+const mcpMetaFor = (type) => type === 'tool'
+    ? pikkuState(null, 'mcp', 'toolsMeta')
+    : type === 'resource'
+        ? pikkuState(null, 'mcp', 'resourcesMeta')
+        : pikkuState(null, 'mcp', 'promptsMeta');
+const WIRE_LEGAL = /^[A-Za-z0-9_-]+$/;
+/**
+ * Registered name -> wire name for every target of one type.
+ *
+ * See `mcp-wire-names-are-assigned-over-the-whole-registry.md`.
+ */
+const mcpWireNames = (type) => {
+    const names = Object.keys(mcpMetaFor(type)).sort();
+    const assigned = new Map();
+    const taken = new Set();
+    for (const name of names) {
+        if (WIRE_LEGAL.test(name)) {
+            assigned.set(name, name);
+            taken.add(name);
+        }
+    }
+    for (const name of names) {
+        if (assigned.has(name)) {
+            continue;
+        }
+        const base = name.replace(/[^A-Za-z0-9_-]/g, '_');
+        let candidate = base;
+        let n = 2;
+        while (taken.has(candidate)) {
+            candidate = `${base}_${n++}`;
+        }
+        assigned.set(name, candidate);
+        taken.add(candidate);
+    }
+    return assigned;
+};
+/** How a registered target's name is spelled on the wire. */
+export const mcpWireName = (type, name) => mcpWireNames(type).get(name) ?? name;
+/** The registered name a client's wire name refers to. */
+export const mcpResolveWireName = (type, wireName) => {
+    for (const [name, wire] of mcpWireNames(type)) {
+        if (wire === wireName) {
+            return name;
+        }
+    }
+    return wireName;
+};

package/dist/wirings/rpc/rpc-types.d.ts

@@ -1,3 +1,4 @@
+import type { CredentialOverrides } from '../credential/credential-overrides.js';
 import type { PikkuRawWire } from '../../types/core.types.js';
 import type { AgentInterruptResult } from '../agent/agent-interrupt.js';
 export type PikkuRPC<Invoke extends (...args: any[]) => any = (...args: any[]) => any, Remote extends (...args: any[]) => any = (...args: any[]) => any, startWorkflow extends (...args: any[]) => any = (...args: any[]) => any, AgentRun extends (...args: any[]) => any = (...args: any[]) => any, AgentStream extends (...args: any[]) => any = (...args: any[]) => any> = {
@@ -47,7 +48,7 @@ export interface ResolvedFunction {
         rpcEndpoint?: string;
         secretOverrides?: Record<string, string>;
         variableOverrides?: Record<string, string>;
-        credentialOverrides?: Record<string, string>;
+        credentialOverrides?: CredentialOverrides;
         /** Set by the consuming app: secrets it lends this instance, as the addon names them */
         secretGrants?: string[];
         /** Set by the consuming app: credentials it lends this instance, as the addon names them */

package/dist/wirings/secret/derive-oauth2-app-secrets.d.ts

@@ -0,0 +1,20 @@
+import type { CredentialDefinitions } from '../credential/credential.types.js';
+import type { SecretDefinitions } from './secret.types.js';
+/**
+ * The app secrets implied by the OAuth2 credentials a project declares.
+ *
+ * An OAuth2 credential always needs the app's client id and secret, and that
+ * pair is the same shape every time — `OAuth2AppCredential`, which is what the
+ * runtime reads it as and what the generated types already say it is. Making
+ * every author restate it as a hand-written `defineSecret` bought nothing and
+ * was silently skipped often enough that deployments were never asked for
+ * credentials their connect flow needed.
+ *
+ * A declaration that already covers the secret id wins, so an author who wants
+ * their own description or `docsUrl` keeps it.
+ *
+ * The derived secret is optional, matching what every hand-written declaration
+ * chose: an addon that also authenticates by API key must still deploy without
+ * an OAuth app configured.
+ */
+export declare const deriveOAuth2AppSecrets: (credentials: CredentialDefinitions, declared: SecretDefinitions) => SecretDefinitions;

package/dist/wirings/secret/derive-oauth2-app-secrets.js

@@ -0,0 +1,47 @@
+/**
+ * The app secrets implied by the OAuth2 credentials a project declares.
+ *
+ * An OAuth2 credential always needs the app's client id and secret, and that
+ * pair is the same shape every time — `OAuth2AppCredential`, which is what the
+ * runtime reads it as and what the generated types already say it is. Making
+ * every author restate it as a hand-written `defineSecret` bought nothing and
+ * was silently skipped often enough that deployments were never asked for
+ * credentials their connect flow needed.
+ *
+ * A declaration that already covers the secret id wins, so an author who wants
+ * their own description or `docsUrl` keeps it.
+ *
+ * The derived secret is optional, matching what every hand-written declaration
+ * chose: an addon that also authenticates by API key must still deploy without
+ * an OAuth app configured.
+ */
+export const deriveOAuth2AppSecrets = (credentials, declared) => {
+    const covered = new Set(declared.map((secret) => secret.secretId));
+    const derived = [];
+    for (const credential of credentials) {
+        const { oauth2 } = credential;
+        if (!oauth2)
+            continue;
+        if (covered.has(oauth2.appCredentialSecretId))
+            continue;
+        covered.add(oauth2.appCredentialSecretId);
+        derived.push({
+            name: `${credential.name}App`,
+            displayName: `${credential.displayName} OAuth App`,
+            description: `OAuth2 app client id and secret for ${credential.displayName}.`,
+            secretId: oauth2.appCredentialSecretId,
+            optional: true,
+            docsUrl: credential.docsUrl,
+            oauth2: {
+                tokenSecretId: oauth2.tokenSecretId,
+                authorizationUrl: oauth2.authorizationUrl,
+                tokenUrl: oauth2.tokenUrl,
+                scopes: oauth2.scopes,
+                pkce: oauth2.pkce,
+                additionalParams: oauth2.additionalParams,
+            },
+            sourceFile: credential.sourceFile,
+        });
+    }
+    return derived;
+};

package/dist/wirings/secret/index.d.ts

@@ -1,3 +1,4 @@
 export { defineSecret } from './secret.types.js';
 export type { CoreSecret, OAuth2CredentialConfig, SecretDefinitionMeta, SecretDefinitionsMeta, SecretDefinitions, } from './secret.types.js';
 export { validateAndBuildSecretDefinitionsMeta } from './validate-secret-definitions.js';
+export { deriveOAuth2AppSecrets } from './derive-oauth2-app-secrets.js';

package/dist/wirings/secret/index.js

@@ -1,2 +1,3 @@
 export { defineSecret } from './secret.types.js';
 export { validateAndBuildSecretDefinitionsMeta } from './validate-secret-definitions.js';
+export { deriveOAuth2AppSecrets } from './derive-oauth2-app-secrets.js';

package/knowledge/decisions/internals/global-middleware-resolves-from-the-root-namespace-too.md

@@ -0,0 +1,32 @@
+---
+type: decision
+title: Global middleware resolves from the root namespace too
+description: An addon's dispatch carries the addon's package name, so reading globals from that namespace alone meant the application's own global middleware never ran for it
+tags: [middleware, addons, packages]
+---
+
+# Global middleware resolves from the root namespace too
+
+`combineMiddleware` collects global middleware from `[null]` for a root
+dispatch, and from `[null, packageName]` for a dispatch belonging to a package.
+
+It previously read one namespace: whichever `packageName` the dispatch carried.
+Application wirings carry `null`, so they were unaffected. A wiring contributed
+by an addon carries that addon's package name, and the application's own globals
+were not in that list — so an addon-contributed MCP tool ran with no session
+middleware at all and refused every caller, while the same function reached over
+HTTP authenticated normally.
+
+Global middleware is application-wide by definition, and an addon's function
+still runs inside the host application, so the root namespace always applies.
+One addon's globals still do not reach another addon's dispatches.
+
+The consequence is that a global written against the application's services now
+runs where those services may not exist — an addon builds its own. Middleware
+that reaches for a service it was not given has to stand down rather than throw;
+see `a-session-middleware-stands-down-where-it-cannot-authenticate.md` in
+`@pikku/better-auth`, which is where this first surfaced.
+
+**What this rules out:** treating a package namespace as a middleware boundary
+in both directions. It is a boundary for what an addon contributes, not a wall
+that the host application's own policy stops at.

package/knowledge/decisions/internals/index.md

@@ -74,6 +74,7 @@ caller is entitled to assume.
 - [Gateway webhook challenges echo bytes not JSON](gateway-webhook-challenges-echo-bytes-not-json.md) — String verification challenges are returned raw with returnsJSON false, because platforms byte-compare the echo and JSON quoting fails the handshake
 - [Gateway wiring is a meta-wiring over HTTP and channels](gateway-wiring-is-a-meta-wiring-over-http-and-channels.md) — wireGateway writes handler implementations into the HTTP and channel state directly while the inspector compiles the corresponding meta, so runtime registration deliberately writes no meta
 - [Generated src paths in pikku meta are absolute](generated-src-paths-in-pikku-meta-are-absolute.md) — emailsMeta.src is resolved by the CLI at generation time, so reading through the project-relative helpers produces a wrong compound path
+- [Global middleware resolves from the root namespace too](global-middleware-resolves-from-the-root-namespace-too.md) — An addon's dispatch carries the addon's package name, so reading globals from that namespace alone meant the application's own global middleware never ran for it
 - [Hot reload reads the changed source, never a compiled copy of it](hot-reload-reads-the-changed-source-never-a-compiled-copy.md) — A leftover .js beside a .ts made the reloader announce a reload while re-registering the previous implementation; project TypeScript is now compiled by the reloader itself
 - [Hot reload writes into the function map captured at startup, not pikkuState's current one](hot-reload-writes-into-the-function-map-captured-at-startup.md) — A dev-server watcher may have swapped in a codegen-scoped map whose writes are discarded on restore, and schemas are deliberately left alone
 - [HTTP request bodies are read once and shared between consumers](http-request-bodies-are-read-once-and-shared.md) — The fetch request wrapper memoises the single-use body and builds web Requests lazily, at the cost of holding the whole body in memory
@@ -87,6 +88,7 @@ caller is entitled to assume.
 - [In-memory workflow history aliases the live step object](in-memory-workflow-history-aliases-the-live-step-object.md) — stepHistory pushes the same StepState reference that steps holds, so later mutations to a step are visible in its history entry
 - [Istanbul statement counts attach to the start line only](istanbul-statement-counts-attach-to-the-start-line-only.md) — The istanbul coverage reader credits a statement's hits to its first line, so an enclosing multi-line statement cannot mask an unexecuted inner one
 - [Local trigger and gateway services assume a single process](local-trigger-and-gateway-services-assume-a-single-process.md) — InMemoryTriggerService and LocalGatewayService start every listener unconditionally with no distributed claiming, so a second instance duplicates every event
+- [MCP wire names are assigned over the whole registry, not derived per name](mcp-wire-names-are-assigned-over-the-whole-registry.md) — Sanitising each name on its own is lossy — `a:b` and `a.b` both become `a_b` — so one of the two targets would be unreachable
 - [Node-only builtins are imported dynamically](node-only-builtins-are-imported-dynamically.md) — V8CoverageService imports node:inspector inside start() so the module stays loadable on runtimes that have no such builtin
 - [One project-shape check, called by both validators](one-project-shape-check-two-validators.md) — workspace validate and fabric validate were separate walks over the same project that duplicated sixteen findings verbatim; the shared half now lives in shared-checks.ts and fabric validate is that plus the deploy-shaped checks
 - [Only functions marked `expose: true` enter a virtual user's catalogue](only-exposed-functions-enter-a-virtual-user-catalogue.md) — Absent is not permissive — an unexposed function 404s over rpc, so offering one spends a step to learn nothing about the product
@@ -111,6 +113,7 @@ caller is entitled to assume.
 - [The embedding model is pinned per service and doc/query embedding is split](the-embedding-model-is-pinned-per-service-and-doc-query-embedding-is-split.md) — AIEmbeddingService fixes its model at construction so index and query share a vector space, and separates embedDocuments from embedQuery for asymmetric models
 - [The in-memory workflow service is inline-only and single-process](the-in-memory-workflow-service-is-inline-only-and-single-process.md) — InMemoryWorkflowService wires no queues and implements withRunLock/withStepLock as pass-throughs, because inline execution has no second holder to exclude
 - [The KEK salt is scoped to the key version, not the secret](the-kek-salt-is-scoped-to-the-key-version.md) — One stored salt per key version means N secrets cost one derivation, which is the point of envelope encryption
+- [The MCP handshake is challenged only when every target is gated](the-mcp-handshake-is-challenged-only-when-every-target-is-gated.md) — A client decides whether a server speaks OAuth from the handshake alone, so a fully-gated server that answers initialize with a 200 is detected as needing no sign-in
 - [The middleware resolution cache is deliberately unbounded](the-middleware-resolution-cache-is-deliberately-unbounded.md) — Its keyspace is the set of registered wires, not request traffic, and middleware is dynamic — so eviction would buy nothing and cost the dedupe guarantee
 - [The per-invocation rpc view is a class, because an object literal with a getter is slow to build](the-per-invocation-rpc-view-is-a-class.md) — An accessor declared on an object literal is defined per instance, which drops the literal off V8's fast construction path — measured at 1.15µs against 0.47µs, on every request
 - [The persona runtime is exported from @pikku/core/persona, never from services](the-persona-runtime-is-exported-from-the-persona-entry-point.md) — Those values reach the actor-flow and agent runners, which no production server runs — and an unbundled deploy loads whatever the import graph names

package/knowledge/decisions/internals/mcp-wire-names-are-assigned-over-the-whole-registry.md

@@ -0,0 +1,39 @@
+---
+type: decision
+title: MCP wire names are assigned over the whole registry, not derived per name
+description: Sanitising each name on its own is lossy — `a:b` and `a.b` both become `a_b` — so one of the two targets would be unreachable
+tags: [mcp, naming]
+---
+
+# MCP wire names are assigned over the whole registry
+
+MCP clients constrain tool and prompt names to `[A-Za-z0-9_-]`. Pikku's
+namespace separator is `:`, so every target contributed by an addon — `bb2:getMe`
+and friends — carries a name the client cannot accept. Clients drop such names
+from the session rather than fail the connection, which reads as the tools simply
+not existing. The names are therefore rewritten at the transport boundary and
+resolved back on the way in; the namespace itself is untouched, since it is what
+dispatch keys on.
+
+The rewrite is computed for **all** names of a target type at once, not for one
+name in isolation. Replacing illegal characters one name at a time is not
+injective: `a:b` and `a.b` both sanitise to `a_b`, so the list handlers would
+advertise one name twice and the resolver could only ever pick one of them. The
+other target becomes unreachable, silently.
+
+The assignment runs in two passes over the sorted names:
+
+1. Every name that is already wire-legal claims itself. A target whose name a
+   client can already spell keeps that spelling, whatever else is registered.
+2. The rest are sanitised, and a collision takes the next free `_2`, `_3`, …
+   suffix.
+
+Sorting makes the result depend only on the set of registered names, so the same
+registry always produces the same wire names, across processes and restarts.
+
+**What this rules out:** a pure `wireName(name)` function. Correctness here is a
+property of the whole registry, and a signature that cannot see the registry
+cannot have it. It also rules out percent-style escaping, which would be
+injective but would turn every namespaced tool into something unreadable in the
+client's UI, for a collision that needs two targets differing only in their
+separator.

package/knowledge/decisions/internals/the-mcp-handshake-is-challenged-only-when-every-target-is-gated.md

@@ -0,0 +1,29 @@
+---
+type: decision
+title: The MCP handshake is challenged only when every target is gated
+description: A client decides whether a server speaks OAuth from the handshake alone, so a fully-gated server that answers initialize with a 200 is detected as needing no sign-in
+tags: [mcp, auth, oauth]
+---
+
+# The MCP handshake is challenged only when every target is gated
+
+`requestNeedsCredentials` challenges `initialize` when
+`mcpEveryTargetRequiresSession()` is true, and only then.
+
+A client decides at connection time whether a server speaks OAuth, and the only
+thing it can decide from is whether the handshake came back `401` with a
+`WWW-Authenticate` header naming the resource metadata. A server that answers
+`initialize` with a `200` and then `401`s every single tool call has told the
+client "no sign-in needed" and then refused it everything. That is how a fully
+gated server ends up shown as open, with no way for the user to sign in — the
+client never offers the option, because it was told there was nothing to offer.
+
+The condition is deliberately all-or-nothing. A server with even one open target
+genuinely is usable anonymously, and challenging its handshake would lock out
+clients that have no credentials to offer at all. An empty registry is not "all
+gated" either: there is nothing there to gate, so the handshake stays open.
+
+**What this rules out:** challenging the handshake whenever _any_ target needs a
+session. The handshake is not the place to express per-target policy — the
+per-target `401` already does that, and a client that has been let in can act on
+it. The handshake only answers "is there a sign-in here at all".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.113",
+  "version": "0.12.114",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pikkujs/pikku.git",

package/src/public-surface.json

@@ -216,7 +216,10 @@
     "getMCPPromptsMeta",
     "getMCPResourcesMeta",
     "getMCPToolsMeta",
+    "mcpEveryTargetRequiresSession",
+    "mcpResolveWireName",
     "mcpTargetRequiresSession",
+    "mcpWireName",
     "runMCPPrompt",
     "runMCPResource",
     "runMCPTool",
@@ -304,6 +307,8 @@
   ],
   "./node": [],
   "./credential": [
+    "buildCredentialResolutions",
+    "credentialOverrideAliases",
     "defineCredential",
     "validateAndBuildCredentialDefinitionsMeta"
   ],
@@ -351,6 +356,7 @@
   ],
   "./secret": [
     "defineSecret",
+    "deriveOAuth2AppSecrets",
     "validateAndBuildSecretDefinitionsMeta"
   ],
   "./variable": [