@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/dist/secret-resolution.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Secret resolver contract (design §10B.1.3). Types live here; the hosted
+ * implementation is `createSecretResolver` in `@opengeni/core` and a static
+ * stub is `createStaticSecretResolver` in `@opengeni/vaults/testing`.
+ *
+ * Invariants: a call resolves all of its references or fails before
+ * dispatch (I2); plaintext only ever lives in `ResolvedSecretValue.material`
+ * and in delivery locals (I1); TOTP codes are computed at dispatch (I4).
+ */
+import type { RequestHumanInputToolInput } from "./index.js";
+import { type SecretReference } from "./secret-references.js";
+import { type SecretClock, type TotpParams } from "./secret-totp.js";
+import type { VaultFieldKind, VaultSource } from "./vaults.js";
+export type SecretPrincipal = {
+    kind: "attempt";
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    attemptId: string;
+    executionGeneration: number;
+} | {
+    kind: "site_viewer";
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    siteId: string;
+    siteVersion: string;
+} | {
+    kind: "human";
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    verifiedHuman: boolean;
+    viaApiKey: boolean;
+};
+export declare const SECRET_USE_SURFACES: readonly ["shell", "stdin", "file_write", "secretfile", "view_image", "run_on", "mcp", "codemode", "site", "browser", "desktop", "human_reveal"];
+export type SecretUseSurface = (typeof SECRET_USE_SURFACES)[number];
+export interface SecretUseContext {
+    surface: SecretUseSurface;
+    toolName: string;
+    operationId?: string;
+    sourceCallId?: string;
+    /**
+     * Where the value goes, for a person approving the use: a page's host, a
+     * machine or a connector name. Never a value.
+     */
+    destination?: string;
+    /**
+     * Looks the destination up when it costs a round trip (a browser page's
+     * host). Called only when a use must ask for approval; failures are ignored.
+     */
+    lookupDestination?: () => Promise<string | null>;
+}
+export type SecretMaterial = {
+    type: "text";
+    value: string;
+}
+/** File fields. */
+ | {
+    type: "bytes";
+    value: Uint8Array;
+}
+/** The code is computed at dispatch (I4). */
+ | {
+    type: "totp";
+    params: TotpParams;
+};
+export interface ResolvedSecretValue {
+    /** `referenceKey(reference)` */
+    key: string;
+    reference: SecretReference;
+    source: VaultSource;
+    vaultId: string;
+    vaultName: string;
+    itemId: string;
+    itemName: string;
+    fieldId: string | null;
+    fieldName: string;
+    /**
+     * The field's kind when the vault reports it. A `text` field (a username,
+     * a host) is not secret: known-value masking does not remember it.
+     */
+    fieldKind?: VaultFieldKind | null;
+    version: number | null;
+    material: SecretMaterial;
+}
+export interface SecretResolver {
+    readonly principal: SecretPrincipal;
+    /** false when agent.capabilities.secrets is off: adapters must pass references through literally (Q-35). */
+    readonly enabled: boolean;
+    /** All-or-nothing (I2). Throws SecretReferenceError. Keys are referenceKey(ref). */
+    resolve(refs: readonly SecretReference[], use: SecretUseContext): Promise<Map<string, ResolvedSecretValue>>;
+}
+export declare const SECRET_REFERENCE_FAILURE_CODES: readonly ["invalid_reference", "not_found", "ambiguous", "denied", "no_primary_field", "provider_unavailable", "provider_rate_limited", "provider_auth_expired", "too_large", "binary_value", "unsupported_shell", "secretfile_not_allowed", "approval_required"];
+export type SecretReferenceFailureCode = (typeof SECRET_REFERENCE_FAILURE_CODES)[number];
+export interface SecretReferenceFailure {
+    raw: string;
+    code: SecretReferenceFailureCode;
+    message: string;
+    /** ambiguous: ready references to choose from (Q-49). */
+    candidates?: string[];
+}
+export declare const SECRET_REFERENCE_ERROR_CODE: "secret_reference_error";
+/**
+ * approval_required: the stored request for the blocked use, and whether
+ * Opengeni itself asked the person (the host's card in the chat, their inbox
+ * and a phone notification). Their answer reaches the agent as a
+ * `secret_use_approval_decided` update; the agent never relays the card.
+ */
+export type SecretUseApprovalAsk = {
+    approvalId: string;
+    /** False only when this run could no longer post in the chat (it was superseded). */
+    asked: boolean;
+};
+/** Thrown by `SecretResolver.resolve` and by delivery adapters before dispatch. */
+export declare class SecretReferenceError extends Error {
+    readonly code: "secret_reference_error";
+    readonly failures: SecretReferenceFailure[];
+    readonly askCard: RequestHumanInputToolInput | null;
+    /** approval_required: the request the person was asked to decide. */
+    readonly approval: SecretUseApprovalAsk | null;
+    constructor(failures: SecretReferenceFailure[], askCard?: RequestHumanInputToolInput | null, approval?: SecretUseApprovalAsk | null);
+    /**
+     * JSON string for tool output: {error, failures, askCard, hint}. A use that
+     * needs approval is told in `hint` that the person was asked; the card
+     * itself never passes through the agent. Never contains values.
+     */
+    toModelOutput(): string;
+}
+export declare function isSecretReferenceError(error: unknown): error is SecretReferenceError;
+/** Materialize at dispatch: text/bytes as-is; TOTP via totpCodeAtDispatch (waits when < 3 s remain). */
+export declare function secretValueAtDispatch(v: ResolvedSecretValue, clock?: SecretClock): Promise<string | Uint8Array>;
+/**
+ * The ready-made ask card for `not_found` failures (§10B.1.3, D11): one
+ * secret question per missing item. Path references name the item in their
+ * last item segment (`Item`, `Item/field` read as Item/field, `Vault/Item/field`);
+ * ID references cannot be asked for by name and are skipped. Returns null
+ * when nothing can be asked. The model submits it unchanged.
+ */
+export declare function buildMissingSecretAskCard(failures: readonly SecretReferenceFailure[], ctx: {
+    hasActingHuman: boolean;
+}): RequestHumanInputToolInput | null;

package/dist/secret-shape-masking.d.ts

@@ -0,0 +1,52 @@
+export type SecretShapeKind = "url-password" | "connection-string-password" | "azure-account-key" | "azure-shared-access-key" | "azure-sas-signature" | "private-key" | "github-token" | "anthropic-key" | "openai-key" | "slack-token" | "stripe-key" | "npm-token" | "gitlab-token" | "google-api-key" | "opengeni-token" | "1password-token" | "jwt";
+export type SecretShapeKindInfo = {
+    /** Plain words for `[masked <label>]`; lower case. */
+    label: string;
+    /** The vault item type and field a captured value is saved as. */
+    itemType: "login" | "api_key" | "note";
+    field: "password" | "value" | "note";
+};
+export declare const SECRET_SHAPE_KINDS: Readonly<Record<SecretShapeKind, SecretShapeKindInfo>>;
+export type SecretShapeMatch = {
+    kind: SecretShapeKind;
+    /** Offsets of the secret part in the scanned text. */
+    start: number;
+    end: number;
+    /** The secret part exactly as written. Never log it. */
+    value: string;
+    /** For URL passwords: the user name written before it, if any. */
+    username?: string;
+};
+/** The fixed marker written where a detected value could not be captured. */
+export declare function secretShapeMaskLabel(kind: SecretShapeKind): string;
+/** Texts longer than this are scanned only in their first part. */
+export declare const SECRET_SHAPE_SCAN_MAX_CHARS = 4000000;
+/**
+ * Every secret-shaped part of `text`, in order and without overlaps (at one
+ * position the earliest start wins, then the longest). Never throws.
+ */
+export declare function detectSecretShapes(text: string): SecretShapeMatch[];
+/**
+ * What replaces one detected part: a label, `undefined` (or an empty string)
+ * for the `[masked <kind>]` marker, or `null` to keep it as written. `text` is
+ * the string the match's offsets refer to.
+ */
+export type SecretShapeReplacement = (match: SecretShapeMatch, text: string) => string | null | undefined;
+/**
+ * `text` with each detected secret part replaced by `replacement(match)`, by
+ * `[masked <kind>]` when it returns undefined or an empty string, or kept as
+ * written when it returns `null`. Idempotent: markers and references are
+ * never detected again. Never throws.
+ */
+export declare function maskSecretShapesInText(text: string, replacement?: SecretShapeReplacement): string;
+/** Deep copy of `value` with secret shapes masked in every string (see `maskSecretShapesInText`). */
+export declare function maskSecretShapes<T>(value: T, replacement?: SecretShapeReplacement, skipKey?: (key: string) => boolean): T;
+/**
+ * The distinct secret values (first occurrence of each) in every string of
+ * `value`, at most `limit`. Never throws.
+ */
+export declare function collectSecretShapes(value: unknown, limit?: number, options?: {
+    skipKey?: (key: string) => boolean;
+    /** Return false to leave a match out (it is neither collected nor masked by the caller). */
+    keep?: (match: SecretShapeMatch, text: string) => boolean;
+}): SecretShapeMatch[];

package/dist/secret-shape-masking.js

@@ -0,0 +1,19 @@
+import {
+  SECRET_SHAPE_KINDS,
+  SECRET_SHAPE_SCAN_MAX_CHARS,
+  collectSecretShapes,
+  detectSecretShapes,
+  maskSecretShapes,
+  maskSecretShapesInText,
+  secretShapeMaskLabel
+} from "./chunk-BMUTAZX5.js";
+export {
+  SECRET_SHAPE_KINDS,
+  SECRET_SHAPE_SCAN_MAX_CHARS,
+  collectSecretShapes,
+  detectSecretShapes,
+  maskSecretShapes,
+  maskSecretShapesInText,
+  secretShapeMaskLabel
+};
+//# sourceMappingURL=secret-shape-masking.js.map

package/dist/secret-shape-masking.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/secret-totp.d.ts

@@ -0,0 +1,41 @@
+export interface TotpParams {
+    secretBase32: string;
+    algorithm: "SHA1" | "SHA256" | "SHA512";
+    digits: 6 | 7 | 8;
+    periodSeconds: number;
+}
+export type SecretClock = {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+};
+export declare const systemSecretClock: SecretClock;
+/** Wait for the next window when fewer than this many ms remain (Q-33). */
+export declare const TOTP_MIN_REMAINING_MS = 3000;
+export declare class TotpInputError extends Error {
+    constructor(message: string);
+}
+/** Uppercase, strip spaces, dashes and padding. */
+export declare function normalizeBase32Secret(input: string): string;
+export declare function decodeBase32(input: string): Uint8Array;
+/**
+ * Accepts an `otpauth://totp/...` URI or a bare Base32 seed (spaces, dashes,
+ * padding and lowercase tolerated). Throws `TotpInputError`.
+ */
+export declare function parseTotpInput(input: string): TotpParams;
+/** True when `input` parses as a TOTP seed or otpauth URI. */
+export declare function isValidTotpInput(input: string): boolean;
+/** Synchronous form of `totpCode` for UI rendering loops. */
+export declare function totpCodeSync(params: TotpParams, atMs: number): string;
+/** The code valid at `atMs` (Unix milliseconds). */
+export declare function totpCode(params: TotpParams, atMs: number): Promise<string>;
+/** Milliseconds left in the window containing `atMs`. */
+export declare function totpRemainingMs(params: TotpParams, atMs: number): number;
+/**
+ * The code to type or send right now. When fewer than 3 s remain in the
+ * current window, waits for the next window so the code is not stale on
+ * arrival (Q-33).
+ */
+export declare function totpCodeAtDispatch(params: TotpParams, clock?: SecretClock): Promise<{
+    code: string;
+    expiresAtMs: number;
+}>;

package/dist/secret-use-approval-question.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Browser/React Native-safe ids of secret approval cards. Deliberately free
+ * of the zod runtime so session-only clients can tell an approval card from
+ * an ordinary question; `secret-use-approvals.ts` re-exports these as the
+ * canonical helpers.
+ */
+/** Question ids `secret-approval:<request uuid>` bind a card to a stored request. */
+export declare const SECRET_USE_APPROVAL_QUESTION_PREFIX = "secret-approval:";
+export declare function secretUseApprovalQuestionId(approvalId: string): string;
+/** The request id a question is bound to, or null for any other question. */
+export declare function secretUseApprovalIdFromQuestionId(questionId: string): string | null;

package/dist/secret-use-approval-question.js

@@ -0,0 +1,11 @@
+import {
+  SECRET_USE_APPROVAL_QUESTION_PREFIX,
+  secretUseApprovalIdFromQuestionId,
+  secretUseApprovalQuestionId
+} from "./chunk-JOTHDW4H.js";
+export {
+  SECRET_USE_APPROVAL_QUESTION_PREFIX,
+  secretUseApprovalIdFromQuestionId,
+  secretUseApprovalQuestionId
+};
+//# sourceMappingURL=secret-use-approval-question.js.map

package/dist/secret-use-approval-question.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/secret-use-approvals.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Approval for each agent use of chosen secrets (docs/secrets.md, "Approval
+ * for each use"). A person marks a vault item, or single fields of it, as
+ * needing their approval. Agents still find and reference the item; the
+ * resolver refuses an unapproved use before any value is read, records the
+ * request and posts the host's own card for it in the chat (with the
+ * person's inbox item and phone notification), so the person always sees
+ * what is really being approved and the agent never relays it. Only the
+ * person the run acts for can answer it. The answer becomes a grant: one
+ * use, this chat, or a time window across their chats in the workspace; the
+ * agent learns it as a `secret_use_approval_decided` update.
+ *
+ * This module must not import runtime values from `./index` (the index
+ * re-exports it); only types cross that edge.
+ */
+import { z } from "zod";
+import type { RequestHumanInputToolInput } from "./index.js";
+import type { SecretUseSurface } from "./secret-resolution.js";
+export { SECRET_USE_APPROVAL_QUESTION_PREFIX, secretUseApprovalIdFromQuestionId, secretUseApprovalQuestionId, } from "./secret-use-approval-question.js";
+export declare const SECRET_USE_APPROVAL_DECISIONS: readonly ["once", "session", "window", "deny"];
+export type SecretUseApprovalDecision = (typeof SECRET_USE_APPROVAL_DECISIONS)[number];
+export type SecretUseGrantScope = Exclude<SecretUseApprovalDecision, "deny">;
+/** "Allow for 1 hour" covers the person's chats in the workspace for this long. */
+export declare const SECRET_USE_APPROVAL_WINDOW_MS: number;
+/** An "Allow once" grant must be used this soon after it is given. */
+export declare const SECRET_USE_APPROVAL_ONCE_TTL_MS: number;
+/** One item field a use needs approval for. Names only, never values. */
+export type SecretUseApprovalTarget = {
+    vaultId: string;
+    itemId: string;
+    /** The field's name key (`secretNameKey`). */
+    fieldKey: string;
+    vaultName: string;
+    itemName: string;
+    fieldName: string;
+};
+/** What the person is asked to approve. */
+export type SecretUseApprovalRequestView = {
+    id: string;
+    targets: readonly SecretUseApprovalTarget[];
+    surface: SecretUseSurface | string;
+    toolName: string;
+    destination: string | null;
+};
+/** "GitHub › password", "GitHub › username and GitHub › password", … */
+export declare function describeSecretUseApprovalTargets(targets: readonly SecretUseApprovalTarget[]): string;
+export declare function describeSecretUseApprovalWhere(view: SecretUseApprovalRequestView): string;
+/**
+ * The host-owned card for one stored request, posted by Opengeni itself as a
+ * `secret_use_approval` human-input request.
+ */
+export declare function secretUseApprovalHumanInput(view: SecretUseApprovalRequestView): RequestHumanInputToolInput;
+/**
+ * What the agent is told when the person answers an approval card: the
+ * summary of its `secret_use_approval_decided` update. Names only, never
+ * values.
+ */
+export declare function secretUseApprovalDecisionSummary(view: SecretUseApprovalRequestView, decision: SecretUseApprovalDecision): string;
+/** One active grant, as shown on the item's page. */
+export declare const SecretUseGrant: z.ZodObject<{
+    id: z.ZodString;
+    scope: z.ZodEnum<{
+        once: "once";
+        session: "session";
+        window: "window";
+    }>;
+    sessionId: z.ZodString;
+    fields: z.ZodArray<z.ZodString>;
+    surface: z.ZodString;
+    toolName: z.ZodString;
+    destination: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodString;
+    decidedBySubjectId: z.ZodNullable<z.ZodString>;
+    expiresAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type SecretUseGrant = z.infer<typeof SecretUseGrant>;
+/** Which uses of an item need approval, and the grants in force for it. */
+export declare const VaultItemApproval: z.ZodObject<{
+    item: z.ZodBoolean;
+    fields: z.ZodArray<z.ZodString>;
+    grants: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        scope: z.ZodEnum<{
+            once: "once";
+            session: "session";
+            window: "window";
+        }>;
+        sessionId: z.ZodString;
+        fields: z.ZodArray<z.ZodString>;
+        surface: z.ZodString;
+        toolName: z.ZodString;
+        destination: z.ZodNullable<z.ZodString>;
+        decidedAt: z.ZodString;
+        decidedBySubjectId: z.ZodNullable<z.ZodString>;
+        expiresAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    canChange: z.ZodBoolean;
+    canAddMarks: z.ZodBoolean;
+    changed: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type VaultItemApproval = z.infer<typeof VaultItemApproval>;
+export declare const SetVaultItemApprovalRequest: z.ZodObject<{
+    item: z.ZodBoolean;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type SetVaultItemApprovalRequest = z.infer<typeof SetVaultItemApprovalRequest>;