@forge-sdk/auth

import * as api from '@forge-sdk/auth';

export interface AgentCapabilityToken {
  /** The unique token identifier. */
  readonly id: string;
  /** The agent DID this token is for. */
  readonly subject: string;
  /** The token issuer. */
  readonly issuer: string;
  /** The intended audience. */
  readonly audience: string;
  /** The granted scopes in 'service:resource:action' format. */
  readonly scopes: readonly string[];
  /** The ISO 8601 timestamp when the token was issued. */
  readonly issuedAt: string;
  /** The ISO 8601 timestamp after which the token is valid. */
  readonly notBefore: string;
  /** The ISO 8601 timestamp at which the token expires. */
  readonly expiresAt: string;
  /** Optional delegation constraints. */
  readonly delegation?: DelegationConstraints;
}

export interface DelegationConstraints {
  /** Whether delegation is allowed. */
  readonly allowDelegation: boolean;
  /** Optional list of allowed delegate agent IDs. Empty = any agent. */
  readonly allowedDelegates: readonly string[];
  /** Minimum TTL reduction in seconds when delegating. */
  readonly minTtlReduction: number;
  /** Maximum delegation depth. */
  readonly maxDelegationDepth: number;
}

export function verifyAct(act: AgentCapabilityToken): void;

export function extractScopes(act: AgentCapabilityToken): string[];

export function actAllowsScope(act: AgentCapabilityToken, scope: string): boolean;

export function scopeImplies(granted: string, requested: string): boolean;

export interface DelegationRequest {
  /** The parent agent's Arsenal ACT. */
  readonly parentAct: AgentCapabilityToken;
  /** The parent agent's OAS DID. */
  readonly parentDid: string;
  /** The child agent's OAS DID. */
  readonly childDid: string;
  /** The scopes requested for the child agent. Must be a subset of the parent's. */
  readonly requestedScopes: readonly string[];
}

export interface DelegationResult {
  /** The child's scopes (verified subset of parent). */
  readonly scopes: readonly string[];
  /** The computed child TTL in seconds. */
  readonly ttlSeconds: number;
  /** The parent's DID for provenance. */
  readonly parentDid: string;
  /** The child's DID. */
  readonly childDid: string;
}

export function delegateCapabilities(request: DelegationRequest): DelegationResult;

export const ForgeAuthErrorCode /* type inferred in source */;

export type ForgeAuthErrorCodeType = (typeof ForgeAuthErrorCode)[keyof typeof ForgeAuthErrorCode];

export class ForgeAuthError extends Error {
  public readonly code: ForgeAuthErrorCodeType;
  static tokenExpired(tokenId: string, agentDid: string, expiredAt: string): ForgeAuthError;
  static insufficientScope(
    agentDid: string,
    requiredScope: string,
    availableScopes: string[]
  ): ForgeAuthError;
  static capabilityEscalation(
    parentDid: string,
    childDid: string,
    requested: string,
    available: string[]
  ): ForgeAuthError;
  static delegationDenied(
    parentDid: string,
    childDid: string,
    reason: string
  ): ForgeAuthError;
  static invalidToken(reason: string): ForgeAuthError;
  isExpired(): boolean;
  isInsufficientScope(): boolean;
  isCapabilityEscalation(): boolean;
  isDelegationDenied(): boolean;
  isInvalidToken(): boolean;
}

export { ForgeAuthError, ForgeAuthErrorCode, type ForgeAuthErrorCodeType } from './error.js';

export {
  type AgentCapabilityToken,
  type DelegationConstraints,
  verifyAct,
  extractScopes,
  actAllowsScope,
  scopeImplies,
} from './capability.js';

export {
  type ToolAuthorizationRequest,
  type ToolAuthorizationDecision,
  ToolAuthorizationDecisionType,
  authorizeToolInvocation,
  isAllowed,
  isDenied,
  isLegacyMode,
  buildToolScope,
} from './tool-auth.js';

export {
  type DelegationRequest,
  type DelegationResult,
  delegateCapabilities,
} from './delegation.js';

export interface ToolAuthorizationRequest {
  /** The OAS DID of the agent requesting tool invocation. */
  readonly agentDid: string;
  /** The name of the tool being invoked. */
  readonly toolName: string;
  /** The tier classification of the tool. */
  readonly toolTier: ToolTier;
  /** The agent's Arsenal ACT, if available. Undefined for legacy mode. */
  readonly act?: AgentCapabilityToken;
}

export const ToolAuthorizationDecisionType /* type inferred in source */;

export type ToolAuthorizationDecisionType =
  (typeof ToolAuthorizationDecisionType)[keyof typeof ToolAuthorizationDecisionType];

export interface ToolAuthorizationDecision {
  /** The decision type. */
  readonly decision: ToolAuthorizationDecisionType;
  /** The denial reason, if denied. */
  readonly reason?: string;
}

export function isAllowed(decision: ToolAuthorizationDecision): boolean;

export function isDenied(decision: ToolAuthorizationDecision): boolean;

export function isLegacyMode(decision: ToolAuthorizationDecision): boolean;

export function buildToolScope(toolName: string): string;

export function authorizeToolInvocation(
  request: ToolAuthorizationRequest
): ToolAuthorizationDecision;