@pikku/core 0.12.30 → 0.12.32

package/CHANGELOG.md

@@ -1,3 +1,108 @@
+## 0.12.32
+
+### 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: fix(core): compose repeated global middleware registrations instead of overwriting
+
+  `addHTTPMiddleware(pattern, …)` and `addTagMiddleware(tag, …)` stored the
+  middleware group with `groups[key] = middleware`, so a second registration for
+  the same pattern/tag silently replaced the first. With Better Auth, generated
+  `auth.gen.ts` registers `addHTTPMiddleware('*', [betterAuthSession()])`, which
+  clobbered an app's own `addHTTPMiddleware('*', [...])` global middleware (cors,
+  session, credential loading) and dropped it from every route.
+
+  Both now append to the existing group (matching `addGlobalMiddleware`, which
+  already appends), so generated auth middleware composes with user-registered
+  global middleware. The route meta lists each pattern once, so the combined
+  group is still applied a single time per request.
+
+- 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.
+
+## 0.12.31
+
+### 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.
+
 ## 0.12.30
 
 ### Patch Changes

package/dist/data-classification.d.ts

@@ -1,11 +1,11 @@
 export type Private<T> = T & {
-    readonly __classification__: 'private';
+    readonly __classification__?: 'private';
 };
 export type Pii<T> = T & {
-    readonly __classification__: 'pii';
+    readonly __classification__?: 'pii';
 };
 export type Secret<T> = T & {
-    readonly __classification__: 'secret';
+    readonly __classification__?: 'secret';
 };
 export type Classification = 'public' | 'private' | 'pii' | 'secret';
 export type AnonymizeStrategy = 'fake:email' | 'fake:name' | 'hash' | 'keep' | null;

package/dist/middleware-runner.js

@@ -69,7 +69,10 @@ const isSortedByPriority = (middlewares) => {
  */
 export const addTagMiddleware = (tag, middleware, packageName = null) => {
     const tagGroups = pikkuState(packageName, 'middleware', 'tagGroup');
-    tagGroups[tag] = middleware;
+    const existing = tagGroups[tag];
+    tagGroups[tag] = existing
+        ? [...existing, ...middleware]
+        : middleware;
     return middleware;
 };
 /**

package/dist/pikku-state.js

@@ -125,6 +125,7 @@ const createEmptyPackageState = () => ({
     package: {
         factories: null,
         singletonServices: null,
+        authFactory: null,
         credentialsMeta: null,
         requiredParentServices: null,
     },

package/dist/services/gopass-secrets.d.ts

@@ -11,5 +11,5 @@ export declare class GopassSecretService implements SecretService {
     hasSecret(key: string): Promise<boolean>;
     setSecret(key: string, value: unknown): Promise<void>;
     deleteSecret(key: string): Promise<void>;
-    getSecrets(keys: string[]): Promise<Record<string, unknown>>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<T>>;
 }

package/dist/services/local-secrets.d.ts

@@ -13,5 +13,5 @@ export declare class LocalSecretService implements SecretService {
     setSecret(key: string, value: unknown): Promise<void>;
     hasSecret(key: string): Promise<boolean>;
     deleteSecret(key: string): Promise<void>;
-    getSecrets(keys: string[]): Promise<Record<string, unknown>>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<T>>;
 }

package/dist/services/local-variables.d.ts

@@ -3,6 +3,7 @@ export declare class LocalVariablesService implements VariablesService {
     private variables;
     constructor(variables?: Record<string, string | undefined>);
     getAll(): Record<string, string | undefined>;
+    getVariables<T extends Record<string, unknown> = Record<string, unknown>>(names: (keyof T & string)[]): Partial<T>;
     get<T = string>(name: string): T | undefined;
     set(name: string, value: unknown): void;
     has(name: string): boolean;

package/dist/services/local-variables.js

@@ -6,6 +6,15 @@ export class LocalVariablesService {
     getAll() {
         return this.variables || {};
     }
+    getVariables(names) {
+        const out = {};
+        for (const name of names) {
+            const value = this.get(name);
+            if (value !== undefined)
+                out[name] = value;
+        }
+        return out;
+    }
     get(name) {
         const raw = this.variables[name];
         if (raw === undefined)

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

@@ -12,5 +12,5 @@ export declare class ScopedSecretService implements SecretService {
     hasSecret(key: string): Promise<boolean>;
     setSecret(_key: string, _value: unknown): Promise<void>;
     deleteSecret(_key: string): Promise<void>;
-    getSecrets(keys: string[]): Promise<Record<string, unknown>>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<T>>;
 }

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

@@ -29,7 +29,7 @@ export class ScopedSecretService {
         throw new Error('deleteSecret is not allowed in scoped secret service');
     }
     async getSecrets(keys) {
-        const allowed = keys.filter((k) => this.allowedKeys.has(k));
-        return this.secrets.getSecrets(allowed);
+        keys.forEach((k) => this.assertAllowed(k));
+        return this.secrets.getSecrets(keys);
     }
 }

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

@@ -31,8 +31,12 @@ export interface SecretService {
     /**
      * Retrieves multiple secrets in a single batch operation.
      * Returns a map of key → value for successfully fetched secrets; missing
-     * keys are omitted rather than throwing.
+     * keys are omitted rather than throwing, so the result is typed as
+     * `Partial<T>` and callers must handle keys that may be absent at runtime.
+     *
+     * Pass a shape as `T` to get a typed result without casting, e.g.
+     * `await secrets.getSecrets<{ FOO: string; BAR: { id: string } }>(['FOO', 'BAR'])`.
      * @param keys - The keys of the secrets to retrieve.
      */
-    getSecrets(keys: string[]): Promise<Record<string, unknown>>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<T>>;
 }

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

@@ -24,7 +24,7 @@ export declare class TypedSecretService<TMap = Record<string, unknown>> implemen
     hasSecret(key: string): Promise<boolean>;
     setSecret<K extends string>(key: K, value: K extends keyof TMap ? TMap[K] : unknown): Promise<void>;
     deleteSecret(key: string): Promise<void>;
-    getSecrets(keys: string[]): Promise<Record<string, unknown>>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<T>>;
     getAllStatus(): Promise<CredentialStatus[]>;
     getMissing(): Promise<CredentialStatus[]>;
 }

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

@@ -15,6 +15,7 @@ export declare class TypedVariablesService<TMap = Record<string, unknown>> imple
     constructor(variables: VariablesService, variablesMeta: Record<string, VariableMeta>);
     get<K extends keyof TMap & string>(name: K): Promise<TMap[K] | undefined> | TMap[K] | undefined;
     get<T = string>(name: string): Promise<T | undefined> | T | undefined;
+    getVariables<T extends Record<string, unknown> = Record<string, unknown>>(names: (keyof T & string)[]): Promise<Partial<T>> | Partial<T>;
     getAll(): Promise<Record<string, string | undefined>> | Record<string, string | undefined>;
     set(name: string, value: unknown): Promise<void> | void;
     has(name: string): Promise<boolean> | boolean;

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

@@ -8,6 +8,9 @@ export class TypedVariablesService {
     get(name) {
         return this.variables.get(name);
     }
+    getVariables(names) {
+        return this.variables.getVariables(names);
+    }
     getAll() {
         return this.variables.getAll();
     }

package/dist/services/variables-service.d.ts

@@ -1,5 +1,14 @@
 export interface VariablesService {
     get<T = string>(name: string): Promise<T | undefined> | T | undefined;
+    /**
+     * Retrieves multiple variables in a single batch operation, mirroring
+     * `SecretService.getSecrets`. Missing variables are omitted rather than
+     * throwing, so the result is typed as `Partial<T>` and callers must handle
+     * keys that may be absent at runtime. Pass a shape as `T` to get a typed
+     * result without casting, e.g.
+     * `await variables.getVariables<{ FOO: string; BAR: string }>(['FOO', 'BAR'])`.
+     */
+    getVariables<T extends Record<string, unknown> = Record<string, unknown>>(names: (keyof T & string)[]): Promise<Partial<T>> | Partial<T>;
     getAll: () => Promise<Record<string, string | undefined>> | Record<string, string | undefined>;
     set: (name: string, value: unknown) => Promise<void> | void;
     has: (name: string) => Promise<boolean> | boolean;

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

@@ -114,6 +114,9 @@ export interface PikkuPackageState {
         } | null;
         /** Cached singleton services for this package */
         singletonServices: CoreSingletonServices | null;
+        /** The pikkuBetterAuth factory, self-registered when auth.ts is evaluated.
+         *  pikkuServices reads it to build and inject the `auth` singleton. */
+        authFactory: ((services: CoreSingletonServices) => unknown | Promise<unknown>) | null;
         /** Credential metadata for this addon package */
         credentialsMeta: Record<string, {
             name: string;

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

@@ -56,7 +56,10 @@ function extractHeadersFromRequest(request, headerKeys) {
  */
 export const addHTTPMiddleware = (pattern, middleware, packageName = null) => {
     const httpGroups = pikkuState(packageName, 'middleware', 'httpGroup');
-    httpGroups[pattern] = middleware;
+    const existing = httpGroups[pattern];
+    httpGroups[pattern] = existing
+        ? [...existing, ...middleware]
+        : middleware;
     return middleware;
 };
 /**

package/dist/wirings/http/pikku-fetch-http-request.js

@@ -13,7 +13,7 @@ export class PikkuFetchHTTPRequest {
     #url;
     #rawBodyText;
     #rawBodyBuffer;
-    #bodyRead = false;
+    #rawBufferPromise;
     constructor(request) {
         this.request = request;
         this.#url = new URL(request.url);
@@ -37,35 +37,49 @@ export class PikkuFetchHTTPRequest {
      * @returns A promise that resolves to the raw request body.
      */
     async arrayBuffer() {
+        return this.#readRawBuffer();
+    }
+    /**
+     * Reads the underlying single-use request body exactly once and memoises both
+     * the in-flight promise and the result. `json()`, `arrayBuffer()`, `body()`
+     * and `toWebRequest()` all funnel through here, so a request whose body is
+     * consumed in more than one place can no longer race on the underlying stream
+     * and fail with "Body has already been used".
+     *
+     * If a second consumer asks for the body while the first read is still in
+     * flight, that is the concurrent double-read that used to crash — now safe,
+     * but warned about so the redundant consumer is found and removed at the
+     * source rather than silently leaning on this cache.
+     */
+    async #readRawBuffer() {
         if (this.#rawBodyBuffer !== undefined) {
             return this.#rawBodyBuffer;
         }
-        if (this.#bodyRead) {
-            if (this.#rawBodyText !== undefined) {
-                const buf = new TextEncoder().encode(this.#rawBodyText)
-                    .buffer;
-                this.#rawBodyBuffer = buf;
-                return buf;
-            }
-            return new ArrayBuffer(0);
+        if (this.#rawBodyText !== undefined) {
+            const buf = new TextEncoder().encode(this.#rawBodyText)
+                .buffer;
+            this.#rawBodyBuffer = buf;
+            return buf;
+        }
+        if (this.#rawBufferPromise !== undefined) {
+            console.warn(`[pikku] request body for ${this.method().toUpperCase()} ${this.path()} ` +
+                `was requested again before the first read resolved — the read is now ` +
+                `shared, but a duplicate body consumer (e.g. middleware calling ` +
+                `toWebRequest just for headers) should be removed.`);
+            return this.#rawBufferPromise;
         }
-        const buf = await this.request.arrayBuffer();
-        this.#rawBodyBuffer = buf;
-        this.#bodyRead = true;
-        return buf;
+        this.#rawBufferPromise = this.request.arrayBuffer().then((buf) => {
+            this.#rawBodyBuffer = buf;
+            return buf;
+        });
+        return this.#rawBufferPromise;
     }
     async #readRawText() {
         if (this.#rawBodyText !== undefined) {
             return this.#rawBodyText;
         }
-        if (this.#rawBodyBuffer !== undefined) {
-            const text = new TextDecoder().decode(this.#rawBodyBuffer);
-            this.#rawBodyText = text;
-            return text;
-        }
-        const text = await this.request.text();
+        const text = new TextDecoder().decode(await this.#readRawBuffer());
         this.#rawBodyText = text;
-        this.#bodyRead = true;
         return text;
     }
     headers() {

package/dist/wirings/http/web-request.js

@@ -21,8 +21,13 @@ export function toWebRequest(req, baseUrl) {
     return new Request(url, {
         method,
         headers,
+        // `pull` (lazy) rather than `start` (eager): the body is only read from the
+        // underlying request when this stream is actually consumed. A consumer that
+        // builds a web Request just to read its headers (e.g. a session middleware
+        // calling getSession({ headers })) never touches the body, so it does zero
+        // body I/O and cannot race the route handler's read of the same request.
         body: new ReadableStream({
-            async start(controller) {
+            async pull(controller) {
                 try {
                     const buffer = await req.arrayBuffer();
                     if (buffer.byteLength > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.30",
+  "version": "0.12.32",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",

package/src/data-classification.ts

@@ -1,6 +1,13 @@
-export type Private<T> = T & { readonly __classification__: 'private' }
-export type Pii<T> = T & { readonly __classification__: 'pii' }
-export type Secret<T> = T & { readonly __classification__: 'secret' }
+// The `__classification__` marker is OPTIONAL on purpose. A required property
+// would make a plain value (e.g. `string`) unassignable to a branded column
+// (`Private<string>`), which breaks ordinary Kysely query operands —
+// `where('email', '=', someString)`, inserts, and `.set(...)`. Making it
+// optional keeps the brand structurally present (so the inspector's PKU910
+// output check still detects it) while allowing plain values to flow IN.
+// See `findPiiPaths` in @pikku/inspector, which reads the level union-aware.
+export type Private<T> = T & { readonly __classification__?: 'private' }
+export type Pii<T> = T & { readonly __classification__?: 'pii' }
+export type Secret<T> = T & { readonly __classification__?: 'secret' }
 
 export type Classification = 'public' | 'private' | 'pii' | 'secret'
 export type AnonymizeStrategy =

package/src/middleware-runner.test.ts

@@ -5,7 +5,7 @@ import {
   addTagMiddleware,
   runMiddleware,
 } from './middleware-runner.js'
-import { resetPikkuState } from './pikku-state.js'
+import { pikkuState, resetPikkuState } from './pikku-state.js'
 import type {
   CorePikkuMiddleware,
   MiddlewarePriority,
@@ -32,6 +32,21 @@ beforeEach(() => {
   resetPikkuState()
 })
 
+describe('addTagMiddleware', () => {
+  test('composes repeated registrations for the same tag', () => {
+    const first: CorePikkuMiddleware = async (_s, _w, next) => next()
+    const second: CorePikkuMiddleware = async (_s, _w, next) => next()
+
+    addTagMiddleware('shared', [first])
+    addTagMiddleware('shared', [second])
+
+    assert.deepEqual(pikkuState(null, 'middleware', 'tagGroup')['shared'], [
+      first,
+      second,
+    ])
+  })
+})
+
 describe('combineMiddleware', () => {
   test('should return empty array when no parameters provided', () => {
     const result = combineMiddleware('http', Math.random().toString())

package/src/middleware-runner.ts

@@ -106,7 +106,10 @@ export const addTagMiddleware = <PikkuMiddleware extends CorePikkuMiddleware>(
   packageName: string | null = null
 ): CorePikkuMiddlewareGroup => {
   const tagGroups = pikkuState(packageName, 'middleware', 'tagGroup')
-  tagGroups[tag] = middleware
+  const existing = tagGroups[tag] as CorePikkuMiddleware[] | undefined
+  tagGroups[tag] = existing
+    ? [...existing, ...(middleware as CorePikkuMiddleware[])]
+    : middleware
   return middleware
 }
 

package/src/pikku-state.ts

@@ -155,6 +155,7 @@ const createEmptyPackageState = (): PikkuPackageState => ({
   package: {
     factories: null,
     singletonServices: null,
+    authFactory: null,
     credentialsMeta: null,
     requiredParentServices: null,
   },

package/src/services/gopass-secrets.ts

@@ -64,13 +64,15 @@ export class GopassSecretService implements SecretService {
     }
   }
 
-  public async getSecrets(keys: string[]): Promise<Record<string, unknown>> {
+  public async getSecrets<
+    T extends Record<string, unknown> = Record<string, unknown>,
+  >(keys: (keyof T & string)[]): Promise<Partial<T>> {
     const results = await Promise.allSettled(keys.map((k) => this.getSecret(k)))
     const out: Record<string, unknown> = {}
     keys.forEach((key, i) => {
       if (results[i].status === 'fulfilled')
         out[key] = (results[i] as PromiseFulfilledResult<unknown>).value
     })
-    return out
+    return out as Partial<T>
   }
 }

package/src/services/local-secrets.ts

@@ -53,13 +53,15 @@ export class LocalSecretService implements SecretService {
     this.localSecrets.delete(key)
   }
 
-  public async getSecrets(keys: string[]): Promise<Record<string, unknown>> {
+  public async getSecrets<
+    T extends Record<string, unknown> = Record<string, unknown>,
+  >(keys: (keyof T & string)[]): Promise<Partial<T>> {
     const results = await Promise.allSettled(keys.map((k) => this.getSecret(k)))
     const out: Record<string, unknown> = {}
     keys.forEach((key, i) => {
       if (results[i].status === 'fulfilled')
         out[key] = (results[i] as PromiseFulfilledResult<unknown>).value
     })
-    return out
+    return out as Partial<T>
   }
 }

package/src/services/local-variables.ts

@@ -9,6 +9,17 @@ export class LocalVariablesService implements VariablesService {
     return this.variables || {}
   }
 
+  public getVariables<
+    T extends Record<string, unknown> = Record<string, unknown>,
+  >(names: (keyof T & string)[]): Partial<T> {
+    const out: Record<string, unknown> = {}
+    for (const name of names) {
+      const value = this.get(name)
+      if (value !== undefined) out[name] = value
+    }
+    return out as Partial<T>
+  }
+
   public get<T = string>(name: string): T | undefined {
     const raw = this.variables[name]
     if (raw === undefined) return undefined

package/src/services/scoped-secret-service.test.ts

@@ -7,6 +7,8 @@ const createMockSecrets = () => ({
   hasSecret: async () => true,
   setSecret: async () => {},
   deleteSecret: async () => {},
+  getSecrets: async <T>(keys: string[]) =>
+    Object.fromEntries(keys.map((key) => [key, { key }])) as T,
 })
 
 describe('ScopedSecretService', () => {
@@ -55,6 +57,24 @@ describe('ScopedSecretService', () => {
     })
   })
 
+  test('should return batch secrets for allowed keys', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1', 'KEY2']))
+    const result = await scoped.getSecrets(['KEY1', 'KEY2'])
+    assert.deepStrictEqual(result, {
+      KEY1: { key: 'KEY1' },
+      KEY2: { key: 'KEY2' },
+    })
+  })
+
+  test('should reject batch getSecrets when any key is not allowed', async () => {
+    const mock = createMockSecrets()
+    const scoped = new ScopedSecretService(mock, new Set(['KEY1']))
+    await assert.rejects(() => scoped.getSecrets(['KEY1', 'KEY2']), {
+      message: 'Access denied to secret key: KEY2',
+    })
+  })
+
   test('should always throw on setSecret', async () => {
     const mock = createMockSecrets()
     const scoped = new ScopedSecretService(mock, new Set(['KEY1']))

package/src/services/scoped-secret-service.ts

@@ -34,8 +34,10 @@ export class ScopedSecretService implements SecretService {
     throw new Error('deleteSecret is not allowed in scoped secret service')
   }
 
-  async getSecrets(keys: string[]): Promise<Record<string, unknown>> {
-    const allowed = keys.filter((k) => this.allowedKeys.has(k))
-    return this.secrets.getSecrets(allowed)
+  async getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(
+    keys: (keyof T & string)[]
+  ): Promise<Partial<T>> {
+    keys.forEach((k) => this.assertAllowed(k))
+    return this.secrets.getSecrets<T>(keys)
   }
 }

package/src/services/secret-service.ts

@@ -31,8 +31,14 @@ export interface SecretService {
   /**
    * Retrieves multiple secrets in a single batch operation.
    * Returns a map of key → value for successfully fetched secrets; missing
-   * keys are omitted rather than throwing.
+   * keys are omitted rather than throwing, so the result is typed as
+   * `Partial<T>` and callers must handle keys that may be absent at runtime.
+   *
+   * Pass a shape as `T` to get a typed result without casting, e.g.
+   * `await secrets.getSecrets<{ FOO: string; BAR: { id: string } }>(['FOO', 'BAR'])`.
    * @param keys - The keys of the secrets to retrieve.
    */
-  getSecrets(keys: string[]): Promise<Record<string, unknown>>
+  getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(
+    keys: (keyof T & string)[]
+  ): Promise<Partial<T>>
 }

package/src/services/typed-secret-service.ts

@@ -43,8 +43,10 @@ export class TypedSecretService<
     return this.secrets.deleteSecret(key)
   }
 
-  async getSecrets(keys: string[]): Promise<Record<string, unknown>> {
-    return this.secrets.getSecrets(keys)
+  async getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(
+    keys: (keyof T & string)[]
+  ): Promise<Partial<T>> {
+    return this.secrets.getSecrets<T>(keys)
   }
 
   async getAllStatus(): Promise<CredentialStatus[]> {

package/src/services/typed-variables-service.ts

@@ -28,6 +28,12 @@ export class TypedVariablesService<
     return this.variables.get(name)
   }
 
+  getVariables<T extends Record<string, unknown> = Record<string, unknown>>(
+    names: (keyof T & string)[]
+  ): Promise<Partial<T>> | Partial<T> {
+    return this.variables.getVariables<T>(names)
+  }
+
   getAll():
     | Promise<Record<string, string | undefined>>
     | Record<string, string | undefined> {

package/src/services/variables-service.ts

@@ -1,5 +1,16 @@
 export interface VariablesService {
   get<T = string>(name: string): Promise<T | undefined> | T | undefined
+  /**
+   * Retrieves multiple variables in a single batch operation, mirroring
+   * `SecretService.getSecrets`. Missing variables are omitted rather than
+   * throwing, so the result is typed as `Partial<T>` and callers must handle
+   * keys that may be absent at runtime. Pass a shape as `T` to get a typed
+   * result without casting, e.g.
+   * `await variables.getVariables<{ FOO: string; BAR: string }>(['FOO', 'BAR'])`.
+   */
+  getVariables<T extends Record<string, unknown> = Record<string, unknown>>(
+    names: (keyof T & string)[]
+  ): Promise<Partial<T>> | Partial<T>
   getAll: () =>
     | Promise<Record<string, string | undefined>>
     | Record<string, string | undefined>