@decaf-ts/integrations 0.11.0 → 0.14.0

package/lib/types/namespaces/rls/rls.types.d.cts

@@ -0,0 +1,77 @@
+/**
+ * @module integrations/namespaces/rls/types
+ * @summary Types shared by the namespace row-level-security template and services.
+ * @description Defines the minimal query-executor contract (compatible with
+ * `pg.Client`/`pg.Pool`), the policy descriptor used to generate DDL, and the
+ * bootstrap/session configuration shapes.
+ */
+/**
+ * @description Minimal asynchronous SQL executor required by the RLS services.
+ * @summary Matches the shape of `pg.Client.query()` without importing `pg` at
+ * runtime. Consumers can pass a `pg.Client`, a `pg.Pool`, or any compatible
+ * wrapper (including test doubles).
+ */
+export interface RlsQueryExecutor {
+    query(sql: string, values?: unknown[]): Promise<{
+        rowCount?: number | null;
+        rows?: unknown[];
+    }>;
+}
+/**
+ * @description A set of row-level-security policies for one table.
+ * @summary Each expression is a PostgreSQL boolean expression evaluated against
+ * the row. `insert` uses `WITH CHECK`; `update` uses `USING` and `WITH CHECK`.
+ */
+export interface RlsPolicySet {
+    /**
+     * @description Table name (optionally schema-qualified) to protect.
+     */
+    table: string;
+    /**
+     * @description `USING` expression for `SELECT`; omit to leave `SELECT` denied.
+     */
+    select?: string;
+    /**
+     * @description `WITH CHECK` expression for `INSERT`; omit to deny inserts.
+     */
+    insert?: string;
+    /**
+     * @description `USING`/`WITH CHECK` expression for `UPDATE`; omit to deny updates.
+     */
+    update?: string;
+    /**
+     * @description `USING` expression for `DELETE`; omit to deny deletes.
+     */
+    delete?: string;
+    /**
+     * @description Whether to also emit `ENABLE`/`FORCE ROW LEVEL SECURITY`.
+     * @default true
+     */
+    enable?: boolean;
+}
+/**
+ * @description Configuration accepted by {@link RlsBootstrapService}.
+ */
+export interface RlsBootstrapConfig {
+    /**
+     * @description Statements to apply instead of the bundled namespace template.
+     * @summary Useful for targeted tests or partial deployments. Statements are
+     * executed sequentially and must be idempotent when applied repeatedly.
+     */
+    statements?: string[];
+    /**
+     * @description Policy sets to generate instead of the bundled namespace policy
+     * template. Function helpers are still emitted unless `statements` is supplied.
+     */
+    policies?: RlsPolicySet[];
+}
+/**
+ * @description Options for {@link runAsPrincipal}.
+ */
+export interface RunAsPrincipalOptions {
+    /**
+     * @description Commit the transaction when the callback succeeds.
+     * @default false — the transaction is rolled back to keep tests isolated.
+     */
+    commit?: boolean;
+}

package/lib/types/namespaces/rls/rls.types.d.mts

@@ -0,0 +1,77 @@
+/**
+ * @module integrations/namespaces/rls/types
+ * @summary Types shared by the namespace row-level-security template and services.
+ * @description Defines the minimal query-executor contract (compatible with
+ * `pg.Client`/`pg.Pool`), the policy descriptor used to generate DDL, and the
+ * bootstrap/session configuration shapes.
+ */
+/**
+ * @description Minimal asynchronous SQL executor required by the RLS services.
+ * @summary Matches the shape of `pg.Client.query()` without importing `pg` at
+ * runtime. Consumers can pass a `pg.Client`, a `pg.Pool`, or any compatible
+ * wrapper (including test doubles).
+ */
+export interface RlsQueryExecutor {
+    query(sql: string, values?: unknown[]): Promise<{
+        rowCount?: number | null;
+        rows?: unknown[];
+    }>;
+}
+/**
+ * @description A set of row-level-security policies for one table.
+ * @summary Each expression is a PostgreSQL boolean expression evaluated against
+ * the row. `insert` uses `WITH CHECK`; `update` uses `USING` and `WITH CHECK`.
+ */
+export interface RlsPolicySet {
+    /**
+     * @description Table name (optionally schema-qualified) to protect.
+     */
+    table: string;
+    /**
+     * @description `USING` expression for `SELECT`; omit to leave `SELECT` denied.
+     */
+    select?: string;
+    /**
+     * @description `WITH CHECK` expression for `INSERT`; omit to deny inserts.
+     */
+    insert?: string;
+    /**
+     * @description `USING`/`WITH CHECK` expression for `UPDATE`; omit to deny updates.
+     */
+    update?: string;
+    /**
+     * @description `USING` expression for `DELETE`; omit to deny deletes.
+     */
+    delete?: string;
+    /**
+     * @description Whether to also emit `ENABLE`/`FORCE ROW LEVEL SECURITY`.
+     * @default true
+     */
+    enable?: boolean;
+}
+/**
+ * @description Configuration accepted by {@link RlsBootstrapService}.
+ */
+export interface RlsBootstrapConfig {
+    /**
+     * @description Statements to apply instead of the bundled namespace template.
+     * @summary Useful for targeted tests or partial deployments. Statements are
+     * executed sequentially and must be idempotent when applied repeatedly.
+     */
+    statements?: string[];
+    /**
+     * @description Policy sets to generate instead of the bundled namespace policy
+     * template. Function helpers are still emitted unless `statements` is supplied.
+     */
+    policies?: RlsPolicySet[];
+}
+/**
+ * @description Options for {@link runAsPrincipal}.
+ */
+export interface RunAsPrincipalOptions {
+    /**
+     * @description Commit the transaction when the callback succeeds.
+     * @default false — the transaction is rolled back to keep tests isolated.
+     */
+    commit?: boolean;
+}

package/lib/types/namespaces/rls/session-binding.d.cts

@@ -0,0 +1,87 @@
+/**
+ * @module integrations/namespaces/rls/session-binding
+ * @summary Maps an authenticated request context to the Postgres session settings consumed by the namespace RLS policies.
+ * @description Exposes {@link namespaceRlsSessionBinding} and the
+ * `namespaceRlsTypeORMOptions()` convenience wrapper: a fail-closed,
+ * config-only seam that turns the principal UUID carried on a decaf `Context`
+ * into a `{ [RLS_SETTINGS.Principal]: principalId }` settings map the TypeORM
+ * adapter binds transaction-locally after `BEGIN`. Nothing is bound when the
+ * context carries no UUID-shaped principal, so Postgres RLS denies
+ * protected-row access instead of silently serving an anonymous read.
+ */
+import type { Context } from "@decaf-ts/core";
+/**
+ * @description Session settings map handed to the persistence adapter's session binding
+ * @summary A plain `name -> value` map of Postgres session variables. The
+ * binding produced here uses exactly one key: {@link RLS_SETTINGS.Principal}
+ * (`app.principal_id`) from `./rls.constants` - the single source of truth
+ * also interpolated by `./rls.template` into the RLS helper functions and
+ * policies - so renaming the setting in one place renames it everywhere.
+ * @typedef {Record<string, string>} NamespaceRlsSessionSettings
+ */
+export type NamespaceRlsSessionSettings = Record<string, string>;
+/**
+ * @description Resolver that maps a request context to RLS session settings
+ * @summary Invoked by the persistence adapter at transaction start with the
+ * request `Context` (if any). Returns the settings to bind
+ * transaction-locally, or `undefined` when nothing should be bound. Must be
+ * synchronous and side-effect free: the consuming adapter treats a throw from
+ * the binding as "no settings" and leaves the transaction unbound (fail
+ * closed).
+ * @typedef {(context?: Context<any>) => NamespaceRlsSessionSettings | undefined} NamespaceRlsSessionBinding
+ */
+export type NamespaceRlsSessionBinding = (context?: Context<any>) => NamespaceRlsSessionSettings | undefined;
+/**
+ * @description Options for the namespace RLS session binding
+ * @summary Lets hosts relocate the context keys the default binding reads and
+ * override the warning sink. The defaults read `principalId` (the resolved
+ * principal UUID carried on the request context) and `user` (the
+ * authenticated identity marker), and warn through `console.warn`.
+ * @interface NamespaceRlsSessionBindingOptions
+ * @property {string} [principalContextKey] - Context key holding the resolved principal UUID. Defaults to `principalId`.
+ * @property {string} [authenticatedContextKey] - Context key that marks the context as authenticated; consulted only to decide whether to warn. Defaults to `user`.
+ * @property {(message: string) => void} [warn] - Warning sink invoked when an authenticated context has no resolvable principal. Defaults to `console.warn`; the message never contains any setting or principal value.
+ */
+export interface NamespaceRlsSessionBindingOptions {
+    principalContextKey?: string;
+    authenticatedContextKey?: string;
+    warn?: (message: string) => void;
+}
+/**
+ * @description Builds the namespace RLS session binding for a request context
+ * @summary Returns a resolver that reads the configured principal context key
+ * (default `principalId`), trims the candidate, and - when it is a
+ * UUID-shaped string - produces
+ * `{ [RLS_SETTINGS.Principal]: principalId }` for the adapter to bind
+ * transaction-locally. Fail closed: a missing context, an absent, empty, or
+ * non-UUID candidate, or a context lookup error yields `undefined`, so
+ * nothing is bound and Postgres RLS denies protected-row access. When the
+ * context looks authenticated (the configured authenticated context key
+ * resolves) but carries no valid principal, the resolver emits a single
+ * warning through the configured `warn` sink (default `console.warn`),
+ * without logging any setting or principal value.
+ * @function namespaceRlsSessionBinding
+ * @param {NamespaceRlsSessionBindingOptions} [options] - Overrides for the context keys and the warning sink.
+ * @returns {NamespaceRlsSessionBinding} The context-to-settings resolver.
+ * @example
+ * const binding = namespaceRlsSessionBinding();
+ * const settings = binding(ctx); // { "app.principal_id": "<uuid>" } or undefined
+ */
+export declare function namespaceRlsSessionBinding(options?: NamespaceRlsSessionBindingOptions): NamespaceRlsSessionBinding;
+/**
+ * @description Builds the `sessionBinding` option for the TypeORM adapter
+ * @summary Convenience wrapper that spreads the namespaced RLS binding into a
+ * TypeORM adapter configuration: merge the returned object into
+ * `TypeORMAdapterOptions` and `TypeORMContextLock` binds the resolved
+ * {@link RLS_SETTINGS.Principal} transaction-locally after `BEGIN`. This is
+ * configuration only - no subclassing or method overrides.
+ * @function namespaceRlsTypeORMOptions
+ * @param {NamespaceRlsSessionBindingOptions} [options] - Overrides forwarded to {@link namespaceRlsSessionBinding}.
+ * @returns {{ sessionBinding: NamespaceRlsSessionBinding }} An object to spread into the TypeORM adapter options.
+ * @example
+ * import { namespaceRlsTypeORMOptions } from "@decaf-ts/integrations/namespaces";
+ * const adapter = new TypeORMAdapter({ ...dataSourceOptions, ...namespaceRlsTypeORMOptions() });
+ */
+export declare function namespaceRlsTypeORMOptions(options?: NamespaceRlsSessionBindingOptions): {
+    sessionBinding: NamespaceRlsSessionBinding;
+};

package/lib/types/namespaces/rls/session-binding.d.mts

@@ -0,0 +1,87 @@
+/**
+ * @module integrations/namespaces/rls/session-binding
+ * @summary Maps an authenticated request context to the Postgres session settings consumed by the namespace RLS policies.
+ * @description Exposes {@link namespaceRlsSessionBinding} and the
+ * `namespaceRlsTypeORMOptions()` convenience wrapper: a fail-closed,
+ * config-only seam that turns the principal UUID carried on a decaf `Context`
+ * into a `{ [RLS_SETTINGS.Principal]: principalId }` settings map the TypeORM
+ * adapter binds transaction-locally after `BEGIN`. Nothing is bound when the
+ * context carries no UUID-shaped principal, so Postgres RLS denies
+ * protected-row access instead of silently serving an anonymous read.
+ */
+import type { Context } from "@decaf-ts/core";
+/**
+ * @description Session settings map handed to the persistence adapter's session binding
+ * @summary A plain `name -> value` map of Postgres session variables. The
+ * binding produced here uses exactly one key: {@link RLS_SETTINGS.Principal}
+ * (`app.principal_id`) from `./rls.constants` - the single source of truth
+ * also interpolated by `./rls.template` into the RLS helper functions and
+ * policies - so renaming the setting in one place renames it everywhere.
+ * @typedef {Record<string, string>} NamespaceRlsSessionSettings
+ */
+export type NamespaceRlsSessionSettings = Record<string, string>;
+/**
+ * @description Resolver that maps a request context to RLS session settings
+ * @summary Invoked by the persistence adapter at transaction start with the
+ * request `Context` (if any). Returns the settings to bind
+ * transaction-locally, or `undefined` when nothing should be bound. Must be
+ * synchronous and side-effect free: the consuming adapter treats a throw from
+ * the binding as "no settings" and leaves the transaction unbound (fail
+ * closed).
+ * @typedef {(context?: Context<any>) => NamespaceRlsSessionSettings | undefined} NamespaceRlsSessionBinding
+ */
+export type NamespaceRlsSessionBinding = (context?: Context<any>) => NamespaceRlsSessionSettings | undefined;
+/**
+ * @description Options for the namespace RLS session binding
+ * @summary Lets hosts relocate the context keys the default binding reads and
+ * override the warning sink. The defaults read `principalId` (the resolved
+ * principal UUID carried on the request context) and `user` (the
+ * authenticated identity marker), and warn through `console.warn`.
+ * @interface NamespaceRlsSessionBindingOptions
+ * @property {string} [principalContextKey] - Context key holding the resolved principal UUID. Defaults to `principalId`.
+ * @property {string} [authenticatedContextKey] - Context key that marks the context as authenticated; consulted only to decide whether to warn. Defaults to `user`.
+ * @property {(message: string) => void} [warn] - Warning sink invoked when an authenticated context has no resolvable principal. Defaults to `console.warn`; the message never contains any setting or principal value.
+ */
+export interface NamespaceRlsSessionBindingOptions {
+    principalContextKey?: string;
+    authenticatedContextKey?: string;
+    warn?: (message: string) => void;
+}
+/**
+ * @description Builds the namespace RLS session binding for a request context
+ * @summary Returns a resolver that reads the configured principal context key
+ * (default `principalId`), trims the candidate, and - when it is a
+ * UUID-shaped string - produces
+ * `{ [RLS_SETTINGS.Principal]: principalId }` for the adapter to bind
+ * transaction-locally. Fail closed: a missing context, an absent, empty, or
+ * non-UUID candidate, or a context lookup error yields `undefined`, so
+ * nothing is bound and Postgres RLS denies protected-row access. When the
+ * context looks authenticated (the configured authenticated context key
+ * resolves) but carries no valid principal, the resolver emits a single
+ * warning through the configured `warn` sink (default `console.warn`),
+ * without logging any setting or principal value.
+ * @function namespaceRlsSessionBinding
+ * @param {NamespaceRlsSessionBindingOptions} [options] - Overrides for the context keys and the warning sink.
+ * @returns {NamespaceRlsSessionBinding} The context-to-settings resolver.
+ * @example
+ * const binding = namespaceRlsSessionBinding();
+ * const settings = binding(ctx); // { "app.principal_id": "<uuid>" } or undefined
+ */
+export declare function namespaceRlsSessionBinding(options?: NamespaceRlsSessionBindingOptions): NamespaceRlsSessionBinding;
+/**
+ * @description Builds the `sessionBinding` option for the TypeORM adapter
+ * @summary Convenience wrapper that spreads the namespaced RLS binding into a
+ * TypeORM adapter configuration: merge the returned object into
+ * `TypeORMAdapterOptions` and `TypeORMContextLock` binds the resolved
+ * {@link RLS_SETTINGS.Principal} transaction-locally after `BEGIN`. This is
+ * configuration only - no subclassing or method overrides.
+ * @function namespaceRlsTypeORMOptions
+ * @param {NamespaceRlsSessionBindingOptions} [options] - Overrides forwarded to {@link namespaceRlsSessionBinding}.
+ * @returns {{ sessionBinding: NamespaceRlsSessionBinding }} An object to spread into the TypeORM adapter options.
+ * @example
+ * import { namespaceRlsTypeORMOptions } from "@decaf-ts/integrations/namespaces";
+ * const adapter = new TypeORMAdapter({ ...dataSourceOptions, ...namespaceRlsTypeORMOptions() });
+ */
+export declare function namespaceRlsTypeORMOptions(options?: NamespaceRlsSessionBindingOptions): {
+    sessionBinding: NamespaceRlsSessionBinding;
+};

package/lib/types/namespaces/services/credential.service.d.cts

@@ -0,0 +1,175 @@
+import { Repository } from "@decaf-ts/core";
+import { DeleteSecretOptions, ExistsSecretOptions, RotateSecretOptions, SecretName, SecretPayload, SecretProvider, SecretReference, StoreSecretOptions } from "../../secrets/core/index.d.cts";
+import { CreateCredentialInput, CredentialSummary, RotateCredentialInput } from "../types.d.cts";
+import { BaseModelService } from "../utils.d.cts";
+import { Credential } from "../models/credential.model.d.cts";
+/**
+ * @description Minimal secret-store contract required by the credential service
+ * @summary Structural subset of the secret service API used for credential
+ * values; `rotate` is optional — when absent, rotation falls back to a
+ * re-store under the same secret name.
+ */
+export interface CredentialSecretStore {
+    /** @description Fixed provider discriminator of the backing implementation. */
+    readonly provider: SecretProvider;
+    /** @description Stores (or overwrites) a named secret payload. */
+    store<T extends SecretPayload = SecretPayload>(name: SecretName, value: T, options?: StoreSecretOptions, ...args: any[]): Promise<SecretReference>;
+    /** @description Deletes a stored secret. */
+    delete(nameOrRef: SecretName | SecretReference, options?: DeleteSecretOptions, ...args: any[]): Promise<void>;
+    /** @description Checks whether a secret exists. */
+    exists(nameOrRef: SecretName | SecretReference, options?: ExistsSecretOptions, ...args: any[]): Promise<boolean>;
+    /** @description Optional in-place rotation of a stored secret value. */
+    rotate?(nameOrRef: SecretName | SecretReference, value: SecretPayload, options?: RotateSecretOptions, ...args: any[]): Promise<SecretReference>;
+}
+/**
+ * @description Injection configuration for the credential service
+ * @summary When `secretService` is omitted, the service lazily boots a
+ * `{@link ModelSecretService}` on first use; when `repository` is omitted,
+ * the base `BaseModelService` repository for `{@link Credential}` is used.
+ */
+export interface CredentialServiceConfig {
+    /** @description Secret store for credential values (must have `provider: "model"`). */
+    secretService?: CredentialSecretStore;
+    /** @description Repository backing the `Credential` metadata rows. */
+    repository?: Repository<Credential, any>;
+}
+/**
+ * @description Manages namespaced credentials and their encrypted secret values
+ * @summary Extends `BaseModelService<Credential>` to create, rotate, read,
+ * list, use-mark, and delete credentials. On create, the secret value is
+ * stored under a generated name first and the metadata row second; if the
+ * row insert fails, the stored secret is force-deleted so no orphaned secret
+ * remains. Deletion mirrors that: the row is removed, then the secret value.
+ * The secret store must resolve to `provider: "model"` — user/runtime
+ * credentials always live in the model-backed secret service.
+ * @category Namespaces
+ * @example
+ * ```ts
+ * import { CredentialService } from "@decaf-ts/integrations/namespaces";
+ *
+ * const credentials = new CredentialService();
+ * const credential = await credentials.createCredential({
+ *   tenantId: "tenant-1",
+ *   name: "deploy-token",
+ *   credentialType: "token",
+ *   secret: { value: "s3cr3t" },
+ * });
+ * await credentials.rotateCredential({
+ *   credentialId: credential.id,
+ *   secret: { value: "n3w-s3cr3t" },
+ * });
+ * ```
+ */
+export declare class CredentialService extends BaseModelService<Credential> {
+    private secretServiceInstance?;
+    /**
+     * @description Creates the credential service
+     * @param {CredentialServiceConfig} [config] - Optional secret store and repository overrides.
+     */
+    constructor(config?: CredentialServiceConfig);
+    /**
+     * @description Resolves the model-backed secret store, booting one lazily
+     * @summary Returns the injected secret service or lazily boots a fresh
+     * `{@link ModelSecretService}`; rejects with a {@link ValidationError} when
+     * the resolved store's provider is not `"model"`.
+     * @returns {Promise<CredentialSecretStore>} The model-backed secret store.
+     * @throws {ValidationError} When the injected store is not model-backed.
+     */
+    protected secretService(): Promise<CredentialSecretStore>;
+    /**
+     * @description Creates a credential row and stores its secret value
+     * @summary Validates the name (trimmed, ≤255 chars, `[A-Za-z0-9][A-Za-z0-9._-]*`),
+     * stores the secret under a generated `credential-<uuid>` name scoped to the
+     * supplied tenant/org-unit/owner, then inserts the metadata row. If the row
+     * insert fails, the just-stored secret is force-deleted before rethrowing.
+     * @param {CreateCredentialInput} input - Credential definition (name, type, secret value, scoping, metadata).
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the store and repository.
+     * @returns {Promise<Credential>} The persisted credential row.
+     * @throws {ValidationError} When the name is invalid.
+     */
+    createCredential(input: CreateCredentialInput, ...args: any[]): Promise<Credential>;
+    /**
+     * @description Replaces a credential's secret value
+     * @summary Uses the backing store's `rotate` when available; otherwise
+     * re-stores the value under the existing secret name with the supplied
+     * version and the credential's tenant/org-unit/owner scoping. The
+     * credential row's `updatedAt` is refreshed afterwards.
+     * @param {RotateCredentialInput} input - Credential id, new secret value, and optional version.
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the store and repository.
+     * @returns {Promise<Credential>} The updated credential row.
+     */
+    rotateCredential(input: RotateCredentialInput, ...args: any[]): Promise<Credential>;
+    /**
+     * @description Reads a credential row by id
+     * @summary Runs the read inside the explicit `withinTransaction` boundary
+     * instead of `@transactional()`: a missing trailing `Context` is synthesized
+     * via `logCtx(args, ..., true)`, then the helper reuses an in-flight
+     * `ContextLock` or opens a new one (`resolveTransactionLock` + `begin`),
+     * rolling back on error and committing when this is the outermost frame. On
+     * a TypeORM-backed repository this binds the context's principal to
+     * `app.principal_id` for the duration of the transaction so namespace RLS
+     * applies to the read.
+     * @param {string} credentialId - The credential id.
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<Credential>} The credential row.
+     */
+    getCredential(credentialId: string, ...args: any[]): Promise<Credential>;
+    /**
+     * @description Lists all credentials as summaries (no secret material)
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<CredentialSummary[]>} Summary records for every credential.
+     */
+    listCredentials(...args: any[]): Promise<CredentialSummary[]>;
+    /**
+     * @description Stamps a credential's `lastUsedAt` timestamp
+     * @summary Runs the read and the update inside one explicit
+     * `withinTransaction` boundary instead of `@transactional()`: a missing
+     * trailing `Context` is synthesized via `logCtx(args, ..., true)`, then the
+     * helper reuses an in-flight `ContextLock` or opens a new one
+     * (`resolveTransactionLock` + `begin`), rolling back on error and committing
+     * when this is the outermost frame. On a TypeORM-backed repository this
+     * binds the context's principal to `app.principal_id` for the duration of
+     * the transaction so namespace RLS applies to both statements.
+     * @param {string} credentialId - The credential id.
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the repository.
+     * @returns {Promise<Credential>} The updated credential row.
+     */
+    markCredentialUsed(credentialId: string, ...args: any[]): Promise<Credential>;
+    /**
+     * @description Deletes a credential row and its stored secret value
+     * @summary Removes the metadata row first, then force-deletes the
+     * referenced secret from the backing store.
+     * @param {string} credentialId - The credential id.
+     * @param {any[]} args - Optional trailing decaf `Context` forwarded to the repository and store.
+     * @returns {Promise<void>} Resolves once the row and secret are removed.
+     */
+    deleteCredential(credentialId: string, ...args: any[]): Promise<void>;
+    /**
+     * @description Runs an operation inside an explicit adapter transaction boundary
+     * @summary Mirrors core's `@transactional()` proxy without the decorator:
+     * reuses the `ContextLock` already cached on the context (`transactionLock`)
+     * when a transaction is in flight, otherwise resolves a fresh lock via
+     * `resolveTransactionLock` and `begin`s it, caching it on the context so
+     * nested frames share it. Depth is tracked so nested calls only decrement;
+     * the outermost frame commits. On error the frame rolls back — unless an
+     * inner frame already ended the transaction — and rethrows the original
+     * error. When the repository exposes no adapter `transactionLock` (e.g.
+     * non-transactional adapters or repository doubles), the operation runs
+     * directly with no transaction. If `ctx` is `undefined`, a standalone
+     * context is synthesized via `this.context`.
+     * @template R - The operation's result type.
+     * @param {Context<any> | undefined} ctx - The caller's decaf `Context`, if one was resolved or synthesized.
+     * @param {() => Promise<R>} operation - The repository work to run inside the transaction.
+     * @returns {Promise<R>} The operation's result, committed when outermost.
+     * @throws {InternalError} When the outermost commit fails.
+     */
+    private withinTransaction;
+    /**
+     * @description Maps a credential row to its API summary shape
+     * @summary Resolves tenant/org-unit/owner relations to their ids and strips
+     * all secret material (the secret value is never exposed).
+     * @param {Credential} credential - The credential row.
+     * @returns {CredentialSummary} The summary record.
+     */
+    private toSummary;
+}