com.l1fe.forge:forge-auth

import com.l1fe.forge.auth.*

public sealed class ForgeAuthError(
message: String,
cause: Throwable?;

public class TokenExpired(
public val actId: String,
public val expiredAt: String,
) : ForgeAuthError(
"Arsenal ACT '$actId' expired at $expiredAt"
)

/**
* The agent does not have sufficient scope in its ACT.
*
* @property agentDid The agent's DID.
* @property actId The ACT identifier.
* @property requiredScope The scope that was required.
* @property availableScopes The scopes available in the ACT.
*/
public class InsufficientScope(
public val agentDid: String,
public val actId: String,
public val requiredScope: String,
public val availableScopes: List<String>,
) : ForgeAuthError(
"agent $agentDid lacks scope '$requiredScope' in Arsenal ACT '$actId'; " +

public val actId: String,
public val expiredAt: String,
) : ForgeAuthError(
"Arsenal ACT '$actId' expired at $expiredAt"
)

/**
* The agent does not have sufficient scope in its ACT.
*
* @property agentDid The agent's DID.
* @property actId The ACT identifier.
* @property requiredScope The scope that was required.
* @property availableScopes The scopes available in the ACT.
*/
public class InsufficientScope(
public val agentDid: String,
public val actId: String,
public val requiredScope: String,
public val availableScopes: List<String>,
) : ForgeAuthError(
"agent $agentDid lacks scope '$requiredScope' in Arsenal ACT '$actId'; " +

public val expiredAt: String,
) : ForgeAuthError(
"Arsenal ACT '$actId' expired at $expiredAt"
)

/**
* The agent does not have sufficient scope in its ACT.
*
* @property agentDid The agent's DID.
* @property actId The ACT identifier.
* @property requiredScope The scope that was required.
* @property availableScopes The scopes available in the ACT.
*/
public class InsufficientScope(
public val agentDid: String,
public val actId: String,
public val requiredScope: String,
public val availableScopes: List<String>,
) : ForgeAuthError(
"agent $agentDid lacks scope '$requiredScope' in Arsenal ACT '$actId'; " +

public class InsufficientScope(
public val agentDid: String,
public val actId: String,
public val requiredScope: String,
public val availableScopes: List<String>,
) : ForgeAuthError(
"agent $agentDid lacks scope '$requiredScope' in Arsenal ACT '$actId'; " +

public val agentDid: String,
public val actId: String,
public val requiredScope: String,
public val availableScopes: List<String>,
) : ForgeAuthError(
"agent $agentDid lacks scope '$requiredScope' in Arsenal ACT '$actId'; " +

public val actId: String,
public val requiredScope: String,
public val availableScopes: List<String>,
) : ForgeAuthError(
"agent $agentDid lacks scope '$requiredScope' in Arsenal ACT '$actId'; " +

public val requiredScope: String,
public val availableScopes: List<String>,
) : ForgeAuthError(
"agent $agentDid lacks scope '$requiredScope' in Arsenal ACT '$actId'; " +

public val availableScopes: List<String>,
) : ForgeAuthError(
"agent $agentDid lacks scope '$requiredScope' in Arsenal ACT '$actId'; " +

public class CapabilityEscalation(
public val parentDid: String,
public val actId: String,
public val requestedScope: String,
public val parentScopes: List<String>,
) : ForgeAuthError(
"capability escalation denied: child requested scope '$requestedScope' but " +
"parent $parentDid ACT '$actId' only grants: " +
parentScopes.joinToString(", ").ifEmpty

public val parentDid: String,
public val actId: String,
public val requestedScope: String,
public val parentScopes: List<String>,
) : ForgeAuthError(
"capability escalation denied: child requested scope '$requestedScope' but " +
"parent $parentDid ACT '$actId' only grants: " +
parentScopes.joinToString(", ").ifEmpty

public val actId: String,
public val requestedScope: String,
public val parentScopes: List<String>,
) : ForgeAuthError(
"capability escalation denied: child requested scope '$requestedScope' but " +
"parent $parentDid ACT '$actId' only grants: " +
parentScopes.joinToString(", ").ifEmpty

public val requestedScope: String,
public val parentScopes: List<String>,
) : ForgeAuthError(
"capability escalation denied: child requested scope '$requestedScope' but " +
"parent $parentDid ACT '$actId' only grants: " +
parentScopes.joinToString(", ").ifEmpty

public val parentScopes: List<String>,
) : ForgeAuthError(
"capability escalation denied: child requested scope '$requestedScope' but " +
"parent $parentDid ACT '$actId' only grants: " +
parentScopes.joinToString(", ").ifEmpty

public class DelegationDenied(
public val reason: String,
) : ForgeAuthError("delegation denied: $reason")

/**
* An ACT is structurally invalid.
*
* @property actId The ACT identifier.
* @property reason The validation failure reason.
*/
public class InvalidAct(
public val actId: String,
public val reason: String,
) : ForgeAuthError("Arsenal ACT '$actId' is invalid: $reason")
}

public val reason: String,
) : ForgeAuthError("delegation denied: $reason")

/**
* An ACT is structurally invalid.
*
* @property actId The ACT identifier.
* @property reason The validation failure reason.
*/
public class InvalidAct(
public val actId: String,
public val reason: String,
) : ForgeAuthError("Arsenal ACT '$actId' is invalid: $reason")
}

public class InvalidAct(
public val actId: String,
public val reason: String,
) : ForgeAuthError("Arsenal ACT '$actId' is invalid: $reason")
}

public val actId: String,
public val reason: String,
) : ForgeAuthError("Arsenal ACT '$actId' is invalid: $reason")
}

public val reason: String,
) : ForgeAuthError("Arsenal ACT '$actId' is invalid: $reason")
}

public data class DelegationConstraints(
@SerialName("allow_delegation")
val allowDelegation: Boolean;

public data class AgentCapabilityToken(
val id: String,
@SerialName("agent_did")
val agentDid: String,
@SerialName("issuer_did")
val issuerDid: String,
val scopes: List<String>,
@SerialName("issued_at")
val issuedAt: Timestamp,
@SerialName("expires_at")
val expiresAt: Timestamp,
@SerialName("delegation_constraints")
val delegationConstraints: DelegationConstraints;

public fun verifyAct(act: AgentCapabilityToken)

public fun extractScopes(act: AgentCapabilityToken): List<String>;

public fun actAllowsScope(act: AgentCapabilityToken, requiredScope: String): Boolean

public fun scopeImplies(granted: String, required: String): Boolean

public data class DelegationRequest(
@SerialName("parent_act")
val parentAct: AgentCapabilityToken,
@SerialName("child_did")
val childDid: String,
@SerialName("requested_scopes")
val requestedScopes: List<String>,
)

/**
* The result of a delegation operation.
*
* @property childAct The delegated ACT for the child agent.
* @property narrowedScopes The scopes that were actually granted (may be a subset of requested).
*/
@Serializable
public data class DelegationResult(
@SerialName("child_act")
val childAct: AgentCapabilityToken,
@SerialName("narrowed_scopes")
val narrowedScopes: List<String>,
)

/**
* Delegate capabilities from a parent to a child agent.
*

public data class DelegationResult(
@SerialName("child_act")
val childAct: AgentCapabilityToken,
@SerialName("narrowed_scopes")
val narrowedScopes: List<String>,
)

/**
* Delegate capabilities from a parent to a child agent.
*
* Enforces the ANVIL rule that child capabilities must be a strict
* subset of parent capabilities. The child's TTL is reduced by
* the delegation constraints.
*
* ANVIL Spec Section 11.2
*
* @param request The delegation request.
* @return The delegation result with the child's ACT.
* @throws ForgeAuthError.DelegationDenied if delegation is not allowed.
* @throws ForgeAuthError.CapabilityEscalation if requested scopes exceed parent's.
* @throws ForgeAuthError.TokenExpired if the parent's ACT has expired.
*/
public fun delegateCapabilities(request: DelegationRequest): DelegationResult

public fun delegateCapabilities(request: DelegationRequest): DelegationResult

public data class ToolAuthorizationRequest(
@SerialName("tool_name")
val toolName: String,
@SerialName("tool_tier")
val toolTier: ToolTier,
@SerialName("agent_did")
val agentDid: String?;

public sealed class ToolAuthorizationDecision

public data class Allowed(val scope: String) : ToolAuthorizationDecision()

/**
* The tool invocation is denied.
*
* @property reason The denial reason.
*/
@Serializable
@SerialName("denied")
public data class Denied(val reason: String) : ToolAuthorizationDecision()

/**
* The tool invocation is in legacy mode (no identity/auth configured).
*
* Legacy mode allows all tools but logs a warning.
*/
@Serializable
@SerialName("legacy_mode")
public data object LegacyMode : ToolAuthorizationDecision()
}

/**
* Authorize a tool invocation against an Arsenal ACT.
*
* Authorization rules per ANVIL 3-tier model:
* - **Platform (Tier 1)**: Always allowed, no ACT check needed.

public data class Denied(val reason: String) : ToolAuthorizationDecision()

/**
* The tool invocation is in legacy mode (no identity/auth configured).
*
* Legacy mode allows all tools but logs a warning.
*/
@Serializable
@SerialName("legacy_mode")
public data object LegacyMode : ToolAuthorizationDecision()
}

/**
* Authorize a tool invocation against an Arsenal ACT.
*
* Authorization rules per ANVIL 3-tier model:
* - **Platform (Tier 1)**: Always allowed, no ACT check needed.
* - **External (Tier 2)**: Requires ACT with matching scope.
* - **Embedded (Tier 3)**: Always allowed (module-scoped).
*
* If no ACT is provided, returns [ToolAuthorizationDecision.LegacyMode].
*
* ANVIL Spec Section 8.7
*
* @param request The authorization request.
* @return The authorization decision.

public data object LegacyMode : ToolAuthorizationDecision()
}

/**
* Authorize a tool invocation against an Arsenal ACT.
*
* Authorization rules per ANVIL 3-tier model:
* - **Platform (Tier 1)**: Always allowed, no ACT check needed.
* - **External (Tier 2)**: Requires ACT with matching scope.
* - **Embedded (Tier 3)**: Always allowed (module-scoped).
*
* If no ACT is provided, returns [ToolAuthorizationDecision.LegacyMode].
*
* ANVIL Spec Section 8.7
*
* @param request The authorization request.
* @return The authorization decision.
*/
public fun authorizeToolInvocation(request: ToolAuthorizationRequest): ToolAuthorizationDecision

public fun authorizeToolInvocation(request: ToolAuthorizationRequest): ToolAuthorizationDecision

public fun buildToolScope(toolName: String): String;