@openagentid/arsenal-sdk/core

declare function addPolicyRule(doc: PolicyDocument, rule: PolicyRule): PolicyDocument;

declare class AgentCapabilityToken {
    readonly claims: TokenClaims;
    readonly signature: TokenSignature | undefined;
    static fromClaims(claims: TokenClaims): AgentCapabilityToken;
    static fromClaimsAndSignature(claims: TokenClaims, signature: TokenSignature): AgentCapabilityToken;
    get id(): string;
    get subject(): string;
    get audience(): string;
    get scopes(): ScopeSet;
    isExpired(now?: Date): boolean;
    isNotYetValid(now?: Date): boolean;
    isTimeValid(now?: Date): boolean;
    remainingTtlMs(now?: Date): number;
    isSigned(): boolean;
    validateStructure(now?: Date): void;
    toCbor(): Uint8Array;
    claimsToCbor(): Uint8Array;
    toBase64Url(): string;
    static fromCbor(bytes: Uint8Array): AgentCapabilityToken;
    static fromBase64Url(s: string): AgentCapabilityToken;
}

declare class AgentId {
    static fromUuid(uuid: string): AgentId;
    static generate(): AgentId;
    asUuid(): string;
    toString(): string;
    toJSON(): string;
    equals(other: AgentId): boolean;
}

declare class AgentIdentity {
    static create(tenantId: TenantId, name: string, publicKeyFingerprint: KeyFingerprint): AgentIdentity;
    get id(): AgentId;
    get publicKeyFingerprint(): KeyFingerprint;
    get tenantId(): TenantId;
    get name(): string;
    get isActive(): boolean;
    get tags(): readonly string[];
    isValid(now?: Date): boolean;
    deactivate(): AgentIdentity;
    withExpiresAt(expiresAt: Date): AgentIdentity;
    withTag(tag: string): AgentIdentity;
    toJSON(): {
        id: string;
        public_key_fingerprint: string;
        tenant_id: string;
        name: string;
        created_at: string;
        expires_at: string | null;
        is_active: boolean;
        tags: readonly string[];
    };
}

interface AgentIdentityData {
    id: AgentId;
    publicKeyFingerprint: KeyFingerprint;
    tenantId: TenantId;
    name: string;
    createdAt: string;
    expiresAt: string | null;
    isActive: boolean;
    tags: readonly string[];
}

declare function allowDelegation(depth: number): DelegationConstraints;

declare class ArsenalError extends Error {
    readonly name = "ArsenalError";
    readonly code: number;
    readonly correlationId: string | undefined;
    readonly context: ErrorContext | undefined;
    constructor(code: number, message: string, options?: {
        correlationId?: string;
        context?: ErrorContext;
        cause?: unknown;
    });
    toString(): string;
    toJSON(): {
        code: number;
        message: string;
        correlation_id?: string;
        context?: ErrorContext;
    };
    withCorrelationId(id: string): ArsenalError;
    withContext(context: ErrorContext): ArsenalError;
    static authenticationFailed(): ArsenalError;
    static tokenExpired(): ArsenalError;
    static tokenSignatureInvalid(): ArsenalError;
    static tokenRevoked(): ArsenalError;
    static scopeExceeded(): ArsenalError;
    static insufficientPermissions(requiredScope: string): ArsenalError;
    static policyDenied(policyId: string): ArsenalError;
    static rateLimitExceeded(retryAfterSecs?: number): ArsenalError;
    static secretNotFound(): ArsenalError;
    static validationFailed(field: string, reason: string): ArsenalError;
    static internal(): ArsenalError;
    static sessionExpired(): ArsenalError;
    static proxyDestinationViolation(domain: string): ArsenalError;
    static ssrfBlocked(): ArsenalError;
    static templateVariableNotFound(variable: string): ArsenalError;
    static invalidTemplateVariable(name: string): ArsenalError;
    static consentRequired(): ArsenalError;
    static consentDenied(): ArsenalError;
    static fingerprintMismatch(): ArsenalError;
    static configurationError(component: string): ArsenalError;
    static cryptoOperationFailed(): ArsenalError;
}

interface AuditEvent {
    id: string;
    timestamp: string;
    kind: AuditEventKindValue;
    severity: AuditSeverityValue;
    tenant_id: string;
    agent_id?: string;
    session_id?: string;
    token_id?: string;
    outcome: AuditOutcomeValue;
    description: string;
    metadata: Readonly<Record<string, unknown>>;
    client_ip?: string;
    user_agent?: string;
    request_id?: string;
    previous_hash?: Uint8Array;
    event_hash?: Uint8Array;
}

declare const AuditEventKind: {
    readonly AgentAuthenticated: "agent_authenticated";
    readonly AuthenticationFailed: "authentication_failed";
    readonly SessionStarted: "session_started";
    readonly SessionEnded: "session_ended";
    readonly CapabilityRequested: "capability_requested";
    readonly CapabilityGranted: "capability_granted";
    readonly CapabilityDenied: "capability_denied";
    readonly TokenRevoked: "token_revoked";
    readonly SecretRead: "secret_read";
    readonly SecretRotated: "secret_rotated";
    readonly ProxyRequest: "proxy_request";
    readonly ProxyDenied: "proxy_denied";
    readonly ConsentRequested: "consent_requested";
    readonly ConsentApproved: "consent_approved";
    readonly ConsentDenied: "consent_denied";
    readonly ConsentRevoked: "consent_revoked";
    readonly PolicyEvaluated: "policy_evaluated";
    readonly PolicyViolation: "policy_violation";
    readonly ConfigChanged: "config_changed";
    readonly KeyRotated: "key_rotated";
};

type AuditEventKindValue = (typeof AuditEventKind)[keyof typeof AuditEventKind];

declare const AuditOutcome: {
    readonly Success: "success";
    readonly Failure: "failure";
    readonly Partial: "partial";
    readonly Pending: "pending";
};

type AuditOutcomeValue = (typeof AuditOutcome)[keyof typeof AuditOutcome];

declare const AuditSeverity: {
    readonly Info: "info";
    readonly Warning: "warning";
    readonly Error: "error";
    readonly Critical: "critical";
};

type AuditSeverityValue = (typeof AuditSeverity)[keyof typeof AuditSeverity];

declare function base64Decode(s: string): Uint8Array;

declare function base64Encode(bytes: Uint8Array): string;

declare function base64UrlDecode(s: string): Uint8Array;

declare function base64UrlEncode(bytes: Uint8Array): string;

declare const BindingType: {
    readonly Required: "required";
    readonly Preferred: "preferred";
};

type BindingTypeValue = (typeof BindingType)[keyof typeof BindingType];

declare function buildTokenClaims(opts: TokenClaimsBuildOptions): TokenClaims;

declare function canDelegateTo(constraints: DelegationConstraints, agentId: string): boolean;

declare function canTransitionTo(from: SessionStateValue, to: SessionStateValue): boolean;

declare class CompositeRateLimiter {
    constructor(limits: RateLimits);
    acquire(): () => void;
}

declare const ConditionOperator: {
    readonly Equals: "equals";
    readonly NotEquals: "not_equals";
    readonly Contains: "contains";
    readonly StartsWith: "starts_with";
    readonly EndsWith: "ends_with";
    readonly Matches: "matches";
    readonly In: "in";
    readonly NotIn: "not_in";
};

type ConditionOperatorValue = (typeof ConditionOperator)[keyof typeof ConditionOperator];

declare const ConsentPolicy: {
    readonly PerVariable: "per_variable";
    readonly PerProvider: "per_provider";
    readonly PerAgent: "per_agent";
};

type ConsentPolicyValue = (typeof ConsentPolicy)[keyof typeof ConsentPolicy];

interface ConsentRecord {
    consent_id: string;
    tenant_id: string;
    agent_did: string;
    human_root_did: string;
    variables: readonly string[];
    destination_domains: readonly string[];
    scopes: readonly string[];
    granted_by: string;
    granted_at: string;
    expires_at: string;
    signature: Uint8Array;
    revocable: boolean;
    revoked: boolean;
    revoked_at?: string;
}

declare function consentRecordCoversDomain(record: ConsentRecord, domain: string): boolean;

declare function consentRecordCoversVariable(record: ConsentRecord, variable: string): boolean;

declare function consentRecordIsValid(record: ConsentRecord, now?: Date): boolean;

declare function consentRecordSigningBytes(record: ConsentRecord): Uint8Array;

interface ConsentRequest {
    request_id: string;
    agent_did: string;
    human_root_did: string;
    variables: readonly string[];
    destination_domains: readonly string[];
    scopes: readonly string[];
    created_at: string;
    expires_at: string;
}

declare function consentRequestIsExpired(req: ConsentRequest, now?: Date): boolean;

declare const ConsentStatus: {
    readonly PreApproved: "pre_approved";
    readonly Approved: "approved";
    readonly Pending: "pending";
    readonly Denied: "denied";
    readonly Revoked: "revoked";
    readonly NotRequired: "not_required";
};

declare function consentStatusAllowsOperation(status: ConsentStatusValue): boolean;

type ConsentStatusValue = (typeof ConsentStatus)[keyof typeof ConsentStatus];

interface ConstraintContext {
    current_time: Date;
    device_id?: string;
    session_id?: string;
    session_key_hash?: Uint8Array;
    origin?: string;
    client_ip?: string;
    environment?: string;
    tags: ReadonlySet<string>;
}

interface Constraints {
    device_binding?: DeviceBinding;
    session_binding?: SessionBinding;
    origin_binding?: OriginBinding;
    network_constraints?: NetworkConstraints;
    time_constraints?: TimeConstraints;
    environment_constraints?: EnvironmentConstraint;
    require_pop: boolean;
}

declare function contextNow(): ConstraintContext;

declare function createAuditEvent(opts: {
    kind: AuditEventKindValue;
    tenant_id: string;
    severity?: AuditSeverityValue;
    outcome?: AuditOutcomeValue;
    description?: string;
    metadata?: Record<string, unknown>;
    agent_id?: string;
    session_id?: string;
    token_id?: string;
    client_ip?: string;
    user_agent?: string;
    request_id?: string;
}): AuditEvent;

declare function createConsentRequest(opts: {
    agent_did: string;
    human_root_did: string;
    variables: readonly string[];
    destination_domains: readonly string[];
    scopes: readonly string[];
    ttl_seconds?: number;
}): ConsentRequest;

declare function createDestinationBinding(allowedDomains: readonly string[], opts?: Partial<Omit<DestinationBinding, "allowed_domains">>): DestinationBinding;

declare function createPolicyDocument(tenantId: string, name: string): PolicyDocument;

declare function createPolicyRequest(agentId: string, tenantId: string, requestedScope: string): PolicyRequest;

declare function createPolicyRule(id: string, effect: PolicyEffectValue, conditions?: readonly PolicyCondition[]): PolicyRule;

declare function createSecretMetadata(tenantId: string, name: string, secretType: SecretTypeValue): SecretMetadata;

declare function createTemplateVariable(name: string): TemplateVariable;

declare function decisionIsAllowed(d: PolicyDecision): boolean;

declare function decisionIsDenied(d: PolicyDecision): boolean;

declare function decodeCbor(bytes: Uint8Array): unknown;

declare function defaultRateLimits(): RateLimits;

declare function defaultUsageBudget(): UsageBudget;

interface DelegationConstraints {
    allow_delegation: boolean;
    max_depth: number;
    delegatable_scopes?: ScopeSet;
    allowed_delegates: readonly string[];
    allow_any_delegate: boolean;
    min_ttl_reduction: number;
    require_approval: boolean;
}

declare function denyDelegation(): DelegationConstraints;

interface DestinationBinding {
    allowed_domains: readonly string[];
    allowed_paths?: readonly string[];
    allowed_methods?: readonly string[];
    allowed_ports?: readonly number[];
    require_tls: boolean;
    allow_subdomains: boolean;
}

interface DeviceBinding {
    device_id: string;
    binding_type: BindingTypeValue;
}

declare class DeviceId {
    static parse(id: string): DeviceId;
    asString(): string;
    toString(): string;
    toJSON(): string;
}

declare function effectiveTimeoutMs(req: ProxyRequest): number;

declare function encodeCbor(value: unknown): Uint8Array;

interface EnvironmentConstraint {
    required_environment?: string;
    required_tags?: ReadonlySet<string>;
    forbidden_tags?: ReadonlySet<string>;
}

declare const ErrorCode: {
    readonly AuthenticationFailed: 1001;
    readonly TokenExpired: 1002;
    readonly TokenSignatureInvalid: 1003;
    readonly PopVerificationFailed: 1004;
    readonly IdentityInvalid: 1005;
    readonly SessionExpired: 1006;
    readonly InsufficientPermissions: 2001;
    readonly ScopeExceeded: 2002;
    readonly PolicyDenied: 2003;
    readonly DelegationInvalid: 2004;
    readonly RateLimitExceeded: 2005;
    readonly BudgetExhausted: 2006;
    readonly TimeConstraintViolation: 3001;
    readonly EnvironmentBindingViolation: 3002;
    readonly NetworkConstraintViolation: 3003;
    readonly DeviceBindingViolation: 3004;
    readonly OriginBindingViolation: 3005;
    readonly SecretNotFound: 4001;
    readonly SecretVersionNotFound: 4002;
    readonly SecretRevoked: 4003;
    readonly SecretRotationInProgress: 4004;
    readonly SecretUnwrapLimitExceeded: 4005;
    readonly CryptoOperationFailed: 4006;
    readonly ValidationFailed: 5001;
    readonly MalformedRequest: 5002;
    readonly InvalidTokenFormat: 5003;
    readonly InvalidScopeFormat: 5004;
    readonly InvalidConstraint: 5005;
    readonly InternalError: 6001;
    readonly StorageError: 6002;
    readonly ConfigurationError: 6003;
    readonly CryptoSubsystemError: 6004;
    readonly AuditError: 6005;
    readonly SerializationFailed: 6006;
    readonly TokenRevoked: 7001;
    readonly AgentDeactivated: 7002;
    readonly TenantSuspended: 7003;
    readonly RevocationStatusUnknown: 7004;
    readonly ProxyDestinationViolation: 8001;
    readonly ProxyRequestFailed: 8002;
    readonly ProxyTimeout: 8003;
    readonly SsrfBlocked: 8004;
    readonly TemplateVariableNotFound: 8005;
    readonly TemplateVariableAccessDenied: 8006;
    readonly InvalidTemplateVariable: 8007;
    readonly OAuthReauthRequired: 8008;
    readonly ConsentRequired: 9001;
    readonly ConsentDenied: 9002;
    readonly ConsentExpired: 9003;
    readonly ConsentRevoked: 9004;
    readonly FingerprintMismatch: 10001;
    readonly FingerprintStateNotFound: 10002;
    readonly DctScopeAmplification: 11001;
    readonly DctDepthExceeded: 11002;
};

type ErrorCodeValue = (typeof ErrorCode)[keyof typeof ErrorCode];

interface ErrorContext {
    operation?: string;
    resource?: string;
    constraint?: string;
    timestamp?: string;
}

declare function extractProxyRequestVariables(req: ProxyRequest): readonly TemplateVariable[];

declare function hashAuditEvent(event: AuditEvent): Promise<Uint8Array>;

declare function hexDecode(s: string): Uint8Array;

declare function hexEncode(bytes: Uint8Array): string;

declare function inferVariablePrefix(name: string): VariablePrefixValue;

declare function ipInCidrRange(ip: string, cidr: string): boolean;

declare function isClientError(code: number): boolean;

declare function isConsentError(code: number): boolean;

declare function isDomainAllowed(binding: DestinationBinding, domain: string): boolean;

declare function isFingerprintError(code: number): boolean;

declare function isMethodAllowed(binding: DestinationBinding, method: string): boolean;

declare function isPathAllowed(binding: DestinationBinding, path: string): boolean;

declare function isPermanentError(code: number): boolean;

declare function isPortAllowed(binding: DestinationBinding, port: number): boolean;

declare function isProxyError(code: number): boolean;

declare function isServerError(code: number): boolean;

declare class KeyFingerprint {
    static fromBytes(bytes: Uint8Array): KeyFingerprint;
    static fromPublicKey(publicKey: Uint8Array): Promise<KeyFingerprint>;
    static fromHex(hex: string): KeyFingerprint;
    asBytes(): Uint8Array;
    toHex(): string;
    toString(): string;
    constantTimeEquals(other: KeyFingerprint): boolean;
    toJSON(): string;
}

declare function latestSecretRef(id: string): SecretRef;

declare const MAX_CHAIN_LENGTH = 10;

declare const MAX_CONDITION_DEPTH = 16;

declare const MAX_DELEGATION_DEPTH = 5;

declare function mergeRateLimits(a: RateLimits, b: RateLimits): RateLimits;

declare function mergeUsageBudget(a: UsageBudget, b: UsageBudget): UsageBudget;

declare function minimalUsageBudget(): UsageBudget;

interface NetworkConstraints {
    allowed_ips?: ReadonlySet<string>;
    denied_ips?: ReadonlySet<string>;
    allowed_cidrs?: readonly string[];
    allowed_asns?: ReadonlySet<number>;
}

declare function noConstraints(): Constraints;

interface OriginBinding {
    allowed_origins: ReadonlySet<string>;
}

declare function parsePermission(s: string): PermissionValue;

declare function parseTemplateVariables(input: string): readonly TemplateVariable[];

declare const Permission: {
    readonly Read: "read";
    readonly Create: "create";
    readonly Update: "update";
    readonly Delete: "delete";
    readonly Admin: "admin";
};

declare function permissionImplies(a: PermissionValue, b: PermissionValue): boolean;

type PermissionValue = (typeof Permission)[keyof typeof Permission];

type PolicyCondition = {
    type: "agent_id";
    operator: ConditionOperatorValue;
    value: string;
} | {
    type: "tenant_id";
    operator: ConditionOperatorValue;
    value: string;
} | {
    type: "scope";
    operator: ConditionOperatorValue;
    value: string;
} | {
    type: "environment";
    operator: ConditionOperatorValue;
    value: string;
} | {
    type: "time_of_day";
    allowed_hours: readonly number[];
} | {
    type: "day_of_week";
    allowed_days: readonly number[];
} | {
    type: "ip_address";
    allowed_cidrs: readonly string[];
} | {
    type: "attribute";
    key: string;
    operator: ConditionOperatorValue;
    value: string;
} | {
    type: "and";
    conditions: readonly PolicyCondition[];
} | {
    type: "or";
    conditions: readonly PolicyCondition[];
} | {
    type: "not";
    condition: PolicyCondition;
};

interface PolicyDecision {
    effect: PolicyEffectValue;
    matched_rule?: string;
    reason?: string;
}

interface PolicyDocument {
    id: string;
    version: number;
    tenant_id: string;
    name: string;
    description?: string;
    rules: readonly PolicyRule[];
    default_effect: PolicyEffectValue;
    is_active: boolean;
    priority: number;
    created_at: string;
    updated_at: string;
    signature?: PolicySignature;
    labels: Readonly<Record<string, string>>;
}

declare const PolicyEffect: {
    readonly Allow: "allow";
    readonly Deny: "deny";
};

type PolicyEffectValue = (typeof PolicyEffect)[keyof typeof PolicyEffect];

declare class PolicyId {
    static parse(id: string): PolicyId;
    static generate(): PolicyId;
    asString(): string;
    toString(): string;
    toJSON(): string;
}

interface PolicyRequest {
    agent_id: string;
    tenant_id: string;
    requested_scope: string;
    timestamp: Date;
    environment?: string;
    client_ip?: string;
    attributes: Readonly<Record<string, string>>;
}

interface PolicyRule {
    id: string;
    description?: string;
    effect: PolicyEffectValue;
    conditions: readonly PolicyCondition[];
    scopes?: ScopeSet;
    constraints?: Constraints;
    rate_limits?: RateLimits;
    budget?: UsageBudget;
}

interface PolicySignature {
    bytes: Uint8Array;
    algorithm: string;
    key_id: string;
    signed_at: string;
}

declare class PrincipalId {
    static parse(id: string): PrincipalId;
    static generate(): PrincipalId;
    static system(): PrincipalId;
    isSystem(): boolean;
    asString(): string;
    toString(): string;
    toJSON(): string;
}

interface ProofOfPossession {
    key_fingerprint: string;
    alg: string;
}

interface ProxyMetadata {
    variables_resolved: readonly string[];
    destination_verified: boolean;
    fingerprint_verified: boolean;
    consent_status: ConsentStatusValue;
    latency_ms: number;
    request_id: string;
}

interface ProxyRequest {
    method: string;
    url: string;
    headers?: Readonly<Record<string, string>>;
    body?: Uint8Array;
    capability_token: string;
    timeout_ms?: number;
}

interface ProxyResponse {
    status: number;
    headers: Readonly<Record<string, string>>;
    body: Uint8Array;
    proxy_metadata: ProxyMetadata;
}

interface RateLimits {
    requests_per_second?: number;
    requests_per_minute?: number;
    requests_per_hour?: number;
    max_concurrent?: number;
    max_request_size?: number;
    max_response_size?: number;
}

interface RemainingBudget {
    requests?: number;
    bytes?: number;
    cost_units?: number;
    secret_unwraps?: number;
}

declare function revokeConsentRecord(record: ConsentRecord, at?: Date): ConsentRecord;

declare function sanitizeFieldName(field: string): string;

declare function sanitizeResourceId(id: string): string;

declare function sanitizeScope(scope: string): string;

declare class Scope {
    static parse(scope: string): Scope;
    static wildcard(): Scope;
    static readOnly(service: string): Scope;
    static fullAccess(service: string): Scope;
    get service(): string;
    get resource(): string;
    get action(): string;
    isWildcard(): boolean;
    implies(other: Scope): boolean;
    asString(): string;
    toString(): string;
    toJSON(): string;
    equals(other: Scope): boolean;
}

declare class ScopeSet {
    static empty(): ScopeSet;
    static single(scope: Scope): ScopeSet;
    static fromStrings(scopes: readonly string[]): ScopeSet;
    static fromScopes(scopes: readonly Scope[]): ScopeSet;
    add(scope: Scope): ScopeSet;
    remove(scope: Scope): ScopeSet;
    contains(scope: Scope): boolean;
    allows(requested: Scope): boolean;
    isSupersetOf(other: ScopeSet): boolean;
    intersection(other: ScopeSet): ScopeSet;
    union(other: ScopeSet): ScopeSet;
    get length(): number;
    isEmpty(): boolean;
    toArray(): readonly Scope[];
    toStrings(): readonly string[];
    [Symbol.iterator](): Iterator<Scope>;
    toJSON(): readonly string[];
}

declare class SecretId {
    static generate(): SecretId;
    static fromString(id: string): SecretId;
    asString(): string;
    toString(): string;
    toJSON(): string;
}

interface SecretMetadata {
    id: string;
    tenant_id: string;
    name: string;
    description?: string;
    secret_type: SecretTypeValue;
    current_version: number;
    versions: readonly SecretVersionInfo[];
    created_at: string;
    updated_at: string;
    expires_at?: string;
    last_rotated_at?: string;
    next_rotation_at?: string;
    is_active: boolean;
    labels: Readonly<Record<string, string>>;
    service?: string;
}

interface SecretRef {
    id: string;
    version?: number;
}

declare const SecretType: {
    readonly ApiKey: "api_key";
    readonly OAuthClientCredentials: "o_auth_client_credentials";
    readonly OAuthAccessToken: "o_auth_access_token";
    readonly OAuthRefreshToken: "o_auth_refresh_token";
    readonly DatabaseCredentials: "database_credentials";
    readonly SshKey: "ssh_key";
    readonly TlsCertificate: "tls_certificate";
    readonly SigningKey: "signing_key";
    readonly EncryptionKey: "encryption_key";
    readonly Generic: "generic";
};

type SecretTypeValue = (typeof SecretType)[keyof typeof SecretType];

declare class SecretValue {
    static fromBytes(bytes: Uint8Array): SecretValue;
    static fromString(s: string): SecretValue;
    asBytes(): Uint8Array;
    asString(): string;
    get length(): number;
    isEmpty(): boolean;
    zeroize(): void;
}

declare class SecretVersion {
    static initial(): SecretVersion;
    static fromNumber(n: number): SecretVersion;
    asNumber(): number;
    next(): SecretVersion;
    isInitial(): boolean;
    toString(): string;
    toJSON(): number;
}

interface SecretVersionInfo {
    version: number;
    created_at: string;
    created_by?: string;
    state: SecretVersionStateValue;
}