import { SecretValue } from "./secret-value.js";

//#region src/secrets/acl.d.ts

/**
 * Per-call context kept in `AsyncLocalStorage`. Carries the current
 * tool's allowlist, identifier, and run/session bookkeeping that the
 * audit log uses for attribution.
 *
 * @stable
 */
interface ToolSecretsContext {
  /** Stable name of the currently-executing tool. */
  readonly toolName: string;
  /** Stable identifier of the run that initiated this scope. */
  readonly runId?: string;
  /** Identifier of the session, if known. */
  readonly sessionId?: string;
  /** Identifier of the agent owning the scope, if known. */
  readonly agentId?: string;
  /** Effective allowlist for the current scope. */
  readonly secretsAllowed: ReadonlyArray<string>;
  /** Lightweight pointer to the parent scope, for sub-agent isolation. */
  readonly parent?: ToolSecretsContext;
}
/**
 * Run `fn` with `ctx` set as the active per-tool secrets context. Used
 * by `@graphorin/tools` and `@graphorin/agent` to wrap tool/agent
 * execution.
 *
 * @stable
 */
declare function withToolSecretsContext<T>(ctx: ToolSecretsContext, fn: () => T): T;
/**
 * Read the active per-tool secrets context, if any. Returns
 * `undefined` outside an explicit `withToolSecretsContext(...)` scope -
 * which means "no ACL enforcement".
 *
 * @stable
 */
declare function getActiveToolSecretsContext(): ToolSecretsContext | undefined;
declare function enforceSecretAcl(key: string): void;
/**
 * Compute the **effective** allowlist for a child scope: intersection
 * of the parent's allowlist and the child's declared list. The
 * intersection is the foundation of the deny-by-default sub-agent
 * inheritance contract - passing an additional key in a child only
 * works when the parent already permits it.
 *
 * @stable
 */
declare function computeEffectiveAllowlist(parent: ToolSecretsContext | undefined, declared: ReadonlyArray<string>): ReadonlyArray<string>;
/**
 * Convenience: run `fn` inside a child scope rooted at the current
 * active context. Used by `@graphorin/agent` to wire sub-agent calls.
 *
 * @stable
 */
declare function withChildToolSecretsContext<T>(child: Omit<ToolSecretsContext, 'parent'>, fn: () => T): T;
/**
 * Mirror of the `@graphorin/core` audit emitter contract for secret
 * unwrap events. Sub-package 03b subscribes through `onSecretValueAudit`
 * (see `secret-value.ts`); the ACL layer additionally emits **scope**
 * events for each `withSecret(...)` invocation.
 *
 * @stable
 */
interface WithSecretAuditEvent {
  readonly action: 'with-secret';
  readonly toolName?: string;
  readonly scopeId: string;
  readonly caller?: string;
  readonly durationMs: number;
  readonly ts: number;
}
/**
 * Callback shape accepted by {@link onWithSecretAudit}.
 *
 * @stable
 */
type WithSecretListener = (event: WithSecretAuditEvent) => void;
/**
 * Subscribe to `withSecret(...)` scope events.
 *
 * @stable
 */
declare function onWithSecretAudit(listener: WithSecretListener): () => void;
/**
 * Reset listener set. Used by tests.
 *
 * @experimental
 */
declare function _resetWithSecretListenersForTesting(): void;
/**
 * Run `fn` with the unwrapped value. Auto-wraps raw strings into a
 * `SecretValue` so callers migrating from raw-string APIs do not have
 * to wrap manually. Records a single audit event per scope.
 *
 * @stable
 */
declare function withSecret<T>(value: string | SecretValue, fn: (raw: string) => T | Promise<T>, opts?: {
  caller?: string;
}): Promise<T>;
//#endregion
export { ToolSecretsContext, WithSecretAuditEvent, WithSecretListener, _resetWithSecretListenersForTesting, computeEffectiveAllowlist, enforceSecretAcl, getActiveToolSecretsContext, onWithSecretAudit, withChildToolSecretsContext, withSecret, withToolSecretsContext };
//# sourceMappingURL=acl.d.ts.map